serega 0.15.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d780c3d344370b36d9e6db64dfdfa08878bfe32885469610ac2314638c878d87
-  data.tar.gz: d282c6466f7b7205a7b524999b85a3e928d79c00ee11445abd26582e0146842c
+  metadata.gz: b291b12115b8ca239642972b103f896f13f02874acdc5663a8f404e02673ca8d
+  data.tar.gz: 18bd88ca4bd77ca147161189efe57b2c544da6cc1b460fc7c694855d4b22edc9
 SHA512:
-  metadata.gz: e2a161487df001b0074d1864770a7dfecd77ef788e187de6e460cd3d2856162cba8777eb807a65a8d4d49471bb50380fc49ffd17f36c16eb52a2ab8b84ed7991
-  data.tar.gz: 4a672090d0893ef8d3945b2528fc9861d245833ec4b21074b73481ab7acbf8fa5207c786cad8496bf022070f3341339522bbf4970c7a554cfa543f002f51f504
+  metadata.gz: d5c5114ed1c1b8b5a0714a340aca263983f5f8cdb24d15c8138124d64520ebafe03f6c64a7985f131ee399fab287ee578889b1affa1e2aa6f4ddacfbb9c8517e
+  data.tar.gz: 4d8191c7081b4650e3328141ec3cc2dc9128a7c4da3a38107e5f2c107d1d70446b67e718a3ffa2ff76e700f80dbdf975da9512d089c86ec552c3dc8a390345d1

data/README.md

@@ -17,13 +17,16 @@ objects and to serialize them to Hash or JSON.
 It has some great features:
 
 - Manually [select serialized fields](#selecting-fields)
+- Secure from malicious queries with [depth_limit][depth_limit] plugin
 - Solutions for N+1 problem (via [batch][batch], [preloads][preloads] or
   [activerecord_preloads][activerecord_preloads] plugins)
 - Built-in object presenter ([presenter][presenter] plugin)
 - Adding custom metadata (via [metadata][metadata] or
   [context_metadata][context_metadata] plugins)
-- Attributes formatters ([formatters][formatters] plugin)
-- Conditional attributes ([if][if] plugin)
+- Value formatters ([formatters][formatters] plugin) helps to transform
+  time, date, money, percentage and any other values same way keeping code dry
+- Conditional attributes - ([if][if] plugin)
+- Auto camelCase keys - [camel_case][camel_case] plugin
 
 ## Installation
 
@@ -64,8 +67,8 @@ class UserSerializer < Serega
   # Regular attribute
   attribute :first_name
 
-  # Option :key specifies method in object
-  attribute :first_name, key: :old_first_name
+  # Option :method specifies method that must be called on serialized object
+  attribute :first_name, method: :old_first_name
 
   # Block is used to define attribute value
   attribute(:first_name) { |user| user.profile&.first_name }
@@ -77,8 +80,9 @@ class UserSerializer < Serega
   # Sub-option :allow_nil by default is false
   attribute :first_name, delegate: { to: :profile, allow_nil: true }
 
-  # Option :delegate can be used with :key sub-option
-  attribute :first_name, delegate: { to: :profile, key: :fname }
+  # Option :delegate can be used with :method sub-option, so method chain here
+  # is user.profile.fname
+  attribute :first_name, delegate: { to: :profile, method: :fname }
 
   # Option :const specifies attribute with specific constant value
   attribute(:type, const: 'user')
@@ -282,7 +286,7 @@ UserSerializer.to_h(bruce, with: fields_as_string)
 
 # With not existing attribute
 fields = %i[first_name enemy]
-fields_as_string = 'first_name,enemy')
+fields_as_string = 'first_name,enemy'
 UserSerializer.new(only: fields).to_h(bruce)
 UserSerializer.to_h(bruce, only: fields)
 UserSerializer.to_h(bruce, only: fields_as_string)
@@ -433,7 +437,7 @@ end
 class UserSerializer < AppSerializer
   attribute :username
   attribute :user_stats,
-    serializer: 'UserStatSerializer'
+    serializer: 'UserStatSerializer',
     value: proc { |user| user },
     preload: nil
 end
@@ -545,15 +549,15 @@ It can be used to find value for attributes in optimal way:
 After including plugin, attributes gain new `:batch` option:
 
 ```ruby
-attribute :name, batch: { key: :id, loader: :name_loader, default: nil }
+attribute :name, batch: { loader: :name_loader, key: :id, default: nil }
 ```
 
 `:batch` option must be a hash with this keys:
 
-- `key` (required) [Symbol, Proc, callable] - Defines current object identifier.
-  Later `loader` will accept array of `keys` to detect this keys values.
 - `loader` (required) [Symbol, Proc, callable] - Defines how to fetch values for
   batch of keys. Receives 3 parameters: keys, context, plan_point.
+- `key` (required) [Symbol, Proc, callable] - Defines current object identifier.
+  Key is optional if plugin was defined with `default_key` option.
 - `default` (optional) - Default value for attribute.
   By default it is `nil` or `[]` when attribute has option `many: true`
   (ex: `attribute :tags, many: true, batch: { ... }`).
@@ -765,7 +769,7 @@ UserSerializer.to_h(nil, meta: { version: '1.0.1' })
 
 ### Plugin :formatters
 
-Allows to define `formatters` and apply them on attributes.
+Allows to define `formatters` and apply them on attribute values.
 
 Config option `config.formatters.add` can be used to add formatters.
 
@@ -888,6 +892,88 @@ Look at [select serialized fields](#selecting-fields) for `:hide` usage examples
  end
 ```
 
+### 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
+
+But its often desired to response with *camelCased* keys.
+By default this can be achieved by specifying attribute name and method directly
+for each attribute: `attribute :firstName, method: first_name`
+
+This plugin transforms all attribute names automatically.
+We use simple regular expression to replace `_x` to `X` for the whole string.
+We make this transformation only once when attribute is defined.
+
+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.
+
+This plugin transforms only attribute keys,
+without affecting `root`, `metadata`, `context_metadata` plugins keys.
+
+If you wish to [select serialized fields](#selecting-fields), you should
+provide them camelCased.
+
+```ruby
+class AppSerializer < Serega
+  plugin :camel_case
+end
+
+class UserSerializer < AppSerializer
+  attribute :first_name
+  attribute :last_name
+  attribute :full_name, camel_case: false,
+    value: proc { |user| [user.first_name, user.last_name].compact.join(" ") }
+end
+
+require "ostruct"
+user = OpenStruct.new(first_name: "Bruce", last_name: "Wayne")
+UserSerializer.to_h(user)
+# => {firstName: "Bruce", lastName: "Wayne", full_name: "Bruce Wayne"}
+
+UserSerializer.new(only: %i[firstName lastName]).to_h(user)
+# => {firstName: "Bruce", lastName: "Wayne"}
+```
+
+### Plugin :depth_limit
+
+Helps to secure from malicious queries that require to serialize too much
+or from accidental serializing of 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.
+
+Any class-level serialization methods also check depth limit as they also
+instantiate serializer.
+
+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:
+
+- `config.depth_limit.limit`
+- `config.depth_limit.limit=`
+
+There are no default limit, but it should be set when enabling plugin.
+
+```ruby
+class AppSerializer < Serega
+  plugin :depth_limit, limit: 10 # set limit for all child classes
+end
+
+class UserSerializer < AppSerializer
+  config.depth_limit.limit = 5 # overrides limit for UserSerializer
+end
+```
+
 ### Plugin :explicit_many_option
 
 Plugin requires to add :many option when adding relationships
@@ -941,6 +1027,7 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 [activerecord_preloads]: #plugin-activerecord_preloads
 [batch]: #plugin-batch
+[camel_case]: #plugin-camel_case
 [context_metadata]: #plugin-context_metadata
 [formatters]: #plugin-formatters
 [metadata]: #plugin-metadata

data/VERSION

@@ -1 +1 @@
-0.15.0
+0.16.0

data/lib/serega/attribute.rb

@@ -22,7 +22,7 @@ class Serega
       attr_reader :many
 
       # Attribute :hide option
-      # @return [Boolean nil] Attribute :hide option
+      # @return [Boolean, nil] Attribute :hide option
       attr_reader :hide
 
       #
@@ -30,7 +30,7 @@ class Serega
       #
       # @param name [Symbol, String] Name of attribute
       # @param opts [Hash] Attribute options
-      # @option opts [Symbol] :key Object method name to fetch attribute value
+      # @option opts [Symbol] :method Object method name to fetch attribute value
       # @option opts [Hash] :delegate Allows to fetch value from nested object
       # @option opts [Boolean] :hide Specify `true` to not serialize this attribute by default
       # @option opts [Boolean] :many Specifies has_many relationship. By default is detected via object.is_a?(Enumerable)

data/lib/serega/attribute_normalizer.rb

@@ -36,12 +36,12 @@ class Serega
       end
 
       #
-      # Symbolized initial attribute key or attribute name if key is empty
+      # Symbolized initial attribute method name
       #
-      # @return [Symbol] Attribute normalized name
+      # @return [Symbol] Attribute normalized method name
       #
-      def key
-        @key ||= prepare_key
+      def method_name
+        @method_name ||= prepare_method_name
       end
 
       #
@@ -121,9 +121,8 @@ class Serega
         init_opts[:serializer]
       end
 
-      def prepare_key
-        key = init_opts[:key]
-        key ? key.to_sym : name
+      def prepare_method_name
+        (init_opts[:method] || init_name).to_sym
       end
 
       def prepare_const_block
@@ -134,7 +133,7 @@ class Serega
       end
 
       def prepare_keyword_block
-        key_method_name = key
+        key_method_name = method_name
         proc do |object|
           object.public_send(key_method_name)
         end
@@ -144,7 +143,7 @@ class Serega
         delegate = init_opts[:delegate]
         return unless delegate
 
-        key_method_name = delegate[:key] || key
+        key_method_name = delegate[:method] || method_name
         delegate_to = delegate[:to]
 
         allow_nil = delegate.fetch(:allow_nil) { self.class.serializer_class.config.delegate_default_allow_nil }

data/lib/serega/config.rb

@@ -15,7 +15,7 @@ class Serega
     DEFAULTS = {
       plugins: [],
       initiate_keys: %i[only with except check_initiate_params].freeze,
-      attribute_keys: %i[key value serializer many hide const delegate].freeze,
+      attribute_keys: %i[method value serializer many hide const delegate].freeze,
       serialize_keys: %i[context many].freeze,
       check_attribute_name: true,
       check_initiate_params: true,

data/lib/serega/object_serializer.rb

@@ -14,7 +14,7 @@ class Serega
 
       # @param plan [SeregaPlan] Serialization plan
       # @param context [Hash] Serialization context
-      # @param many [TrueClass|FalseClass] is object is enumerable
+      # @param many [Boolean] is object is enumerable
       # @param opts [Hash] Any custom options
       #
       # @return [SeregaObjectSerializer] New SeregaObjectSerializer

data/lib/serega/plan.rb

@@ -22,7 +22,7 @@ class Serega
       #
       def call(opts)
         max_cache_size = serializer_class.config.max_cached_plans_per_serializer_count
-        return new(opts) if max_cache_size.zero?
+        return new(nil, opts) if max_cache_size.zero?
 
         cached_plan_for(opts, max_cache_size)
       end
@@ -33,7 +33,7 @@ class Serega
         @cache ||= {}
         cache_key = construct_cache_key(opts)
 
-        plan = @cache[cache_key] ||= new(opts)
+        plan = @cache[cache_key] ||= new(nil, opts)
         @cache.shift if @cache.length > max_cache_size
         plan
       end
@@ -61,25 +61,26 @@ class Serega
       # @return [SeregaPlanPoint, nil]
       attr_reader :parent_plan_point
 
-      # Sets new parent plan point
-      # @return [SeregaPlanPoint] new parent plan point
-      attr_writer :parent_plan_point
-
       # Serialization points
       # @return [Array<SeregaPlanPoint>] points to serialize
       attr_reader :points
 
       #
-      # Instantiate new serialization plan.
+      # Instantiate new serialization plan
+      #
+      # Patched by
+      #  - depth_limit plugin, which checks depth limit is not exceeded when adding new plan
       #
-      # @param modifiers Serialization parameters
+      # @param parent_plan_point [SeregaPlanPoint, nil] Parent plan_point
+      # @param modifiers [Hash] Serialization parameters
       # @option modifiers [Hash] :only The only attributes to serialize
       # @option modifiers [Hash] :except Attributes to hide
       # @option modifiers [Hash] :with Hidden attributes to serialize additionally
       #
       # @return [SeregaPlan] Serialization plan
       #
-      def initialize(modifiers)
+      def initialize(parent_plan_point, modifiers)
+        @parent_plan_point = parent_plan_point
         @points = attributes_points(modifiers)
       end
 
@@ -107,8 +108,7 @@ class Serega
               {only: only[name], with: with[name], except: except[name]}
             end
 
-          point = serializer_class::SeregaPlanPoint.new(attribute, child_fields)
-          point.plan = self
+          point = serializer_class::SeregaPlanPoint.new(self, attribute, child_fields)
           points << point.freeze
         end
 

data/lib/serega/plan_point.rb

@@ -13,7 +13,7 @@ class Serega
 
       # Link to current plan this point belongs to
       # @return [SeregaAttribute] Current plan
-      attr_accessor :plan
+      attr_reader :plan
 
       # Shows current attribute
       # @return [SeregaAttribute] Current attribute
@@ -44,6 +44,7 @@ class Serega
       #
       # Initializes plan point
       #
+      # @param plan [SeregaPlan] Current plan this point belongs to
       # @param attribute [SeregaAttribute] Attribute to construct plan point
       # @param modifiers Serialization parameters
       # @option modifiers [Hash] :only The only attributes to serialize
@@ -52,7 +53,8 @@ class Serega
       #
       # @return [SeregaPlanPoint] New plan point
       #
-      def initialize(attribute, modifiers = nil)
+      def initialize(plan, attribute, modifiers = nil)
+        @plan = plan
         @attribute = attribute
         @modifiers = modifiers
         set_normalized_vars
@@ -79,9 +81,7 @@ class Serega
 
         fields = modifiers || FROZEN_EMPTY_HASH
 
-        plan = serializer::SeregaPlan.new(fields)
-        plan.parent_plan_point = self
-        plan
+        serializer::SeregaPlan.new(self, fields)
       end
     end
 

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

@@ -77,7 +77,7 @@ class Serega
       # @return [void]
       #
       def self.load_plugin(serializer_class, **_opts)
-        require_relative "./lib/preloader"
+        require_relative "lib/preloader"
 
         serializer_class.include(InstanceMethods)
       end

data/lib/serega/plugins/batch/batch.rb

@@ -79,18 +79,18 @@ class Serega
       # @return [void]
       #
       def self.load_plugin(serializer_class, **_opts)
-        require_relative "./lib/batch_config"
-        require_relative "./lib/loader"
-        require_relative "./lib/loaders"
-        require_relative "./lib/modules/attribute"
-        require_relative "./lib/modules/attribute_normalizer"
-        require_relative "./lib/modules/check_attribute_params"
-        require_relative "./lib/modules/config"
-        require_relative "./lib/modules/object_serializer"
-        require_relative "./lib/modules/plan_point"
-        require_relative "./lib/validations/check_batch_opt_key"
-        require_relative "./lib/validations/check_batch_opt_loader"
-        require_relative "./lib/validations/check_opt_batch"
+        require_relative "lib/batch_config"
+        require_relative "lib/loader"
+        require_relative "lib/loaders"
+        require_relative "lib/modules/attribute"
+        require_relative "lib/modules/attribute_normalizer"
+        require_relative "lib/modules/check_attribute_params"
+        require_relative "lib/modules/config"
+        require_relative "lib/modules/object_serializer"
+        require_relative "lib/modules/plan_point"
+        require_relative "lib/validations/check_batch_opt_key"
+        require_relative "lib/validations/check_batch_opt_loader"
+        require_relative "lib/validations/check_opt_batch"
 
         serializer_class.extend(ClassMethods)
         serializer_class.include(InstanceMethods)
@@ -121,18 +121,18 @@ class Serega
         serializer_class.const_set(:SeregaBatchLoader, batch_loader_class)
 
         if serializer_class.plugin_used?(:activerecord_preloads)
-          require_relative "./lib/plugins_extensions/activerecord_preloads"
+          require_relative "lib/plugins_extensions/activerecord_preloads"
           serializer_class::SeregaBatchLoader.include(PluginsExtensions::ActiveRecordPreloads::BatchLoaderInstanceMethods)
         end
 
         if serializer_class.plugin_used?(:formatters)
-          require_relative "./lib/plugins_extensions/formatters"
+          require_relative "lib/plugins_extensions/formatters"
           serializer_class::SeregaBatchLoader.include(PluginsExtensions::Formatters::BatchLoaderInstanceMethods)
           serializer_class::SeregaAttribute.include(PluginsExtensions::Formatters::SeregaAttributeInstanceMethods)
         end
 
         if serializer_class.plugin_used?(:preloads)
-          require_relative "./lib/plugins_extensions/preloads"
+          require_relative "lib/plugins_extensions/preloads"
           serializer_class::SeregaAttributeNormalizer.include(PluginsExtensions::Preloads::AttributeNormalizerInstanceMethods)
         end
 

data/lib/serega/plugins/batch/lib/validations/check_opt_batch.rb

@@ -23,7 +23,7 @@ class Serega
             SeregaValidations::Utils::CheckOptIsHash.call(opts, :batch)
 
             batch = opts[:batch]
-            SeregaValidations::Utils::CheckAllowedKeys.call(batch, %i[key loader default])
+            SeregaValidations::Utils::CheckAllowedKeys.call(batch, %i[key loader default], :batch)
 
             check_batch_opt_key(batch, serializer_class)
             check_batch_opt_loader(batch)
@@ -50,7 +50,7 @@ class Serega
           end
 
           def check_usage_with_other_params(opts, block)
-            raise SeregaError, "Option :batch can not be used together with option :key" if opts.key?(:key)
+            raise SeregaError, "Option :batch can not be used together with option :method" if opts.key?(:method)
             raise SeregaError, "Option :batch can not be used together with option :value" if opts.key?(:value)
             raise SeregaError, "Option :batch can not be used together with option :const" if opts.key?(:const)
             raise SeregaError, "Option :batch can not be used together with option :delegate" if opts.key?(:delegate)

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

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    #
+    # 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
+    #
+    # 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`
+    #
+    # 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.
+    #
+    # @example Define plugin
+    #  class AppSerializer < Serega
+    #    plugin :camel_case
+    #  end
+    #
+    #  class UserSerializer < AppSerializer
+    #    attribute :first_name
+    #    attribute :last_name
+    #    attribute :full_name, camel_case: false, value: proc { |user| [user.first_name, user.last_name].compact.join(" ") }
+    #  end
+    #
+    #  require "ostruct"
+    #  user = OpenStruct.new(first_name: "Bruce", last_name: "Wayne")
+    #  UserSerializer.to_h(user) # {firstName: "Bruce", lastName: "Wayne", full_name: "Bruce Wayne"}
+    #
+    module CamelCase
+      # Default camel-case transformation
+      TRANSFORM_DEFAULT = proc { |attribute_name|
+        attribute_name.gsub!(/_[a-z]/) { |m| m[-1].upcase! }
+        attribute_name
+      }
+
+      # @return [Symbol] Plugin name
+      def self.plugin_name
+        :camel_case
+      end
+
+      #
+      # Applies plugin code to specific serializer
+      #
+      # @param serializer_class [Class<Serega>] Current serializer class
+      # @param _opts [Hash] Loaded plugins options
+      #
+      # @return [void]
+      #
+      def self.load_plugin(serializer_class, **_opts)
+        serializer_class::SeregaConfig.include(ConfigInstanceMethods)
+        serializer_class::SeregaAttributeNormalizer.include(AttributeNormalizerInstanceMethods)
+        serializer_class::CheckAttributeParams.include(CheckAttributeParamsInstanceMethods)
+      end
+
+      #
+      # Adds config options and runs other callbacks after plugin was loaded
+      #
+      # @param serializer_class [Class<Serega>] Current serializer class
+      # @param opts [Hash] loaded plugins opts
+      #
+      # @return [void]
+      #
+      def self.after_load_plugin(serializer_class, **opts)
+        config = serializer_class.config
+        config.opts[:camel_case] = {}
+        config.camel_case.transform = opts[:transform] || TRANSFORM_DEFAULT
+
+        config.attribute_keys << :camel_case
+      end
+
+      #
+      # Config class additional/patched instance methods
+      #
+      # @see Serega::SeregaConfig
+      #
+      module ConfigInstanceMethods
+        # @return [Serega::SeregaPlugins::CamelCase::CamelCaseConfig] `camel_case` plugin config
+        def camel_case
+          @camel_case ||= CamelCaseConfig.new(opts.fetch(:camel_case))
+        end
+      end
+
+      #
+      # Serega::SeregaValidations::CheckAttributeParams additional/patched class methods
+      #
+      # @see Serega::SeregaValidations::CheckAttributeParams
+      #
+      module CheckAttributeParamsInstanceMethods
+        private
+
+        def check_opts
+          super
+          CheckOptCamelCase.call(opts)
+        end
+      end
+
+      #
+      # Validator for attribute :camel_case option
+      #
+      class CheckOptCamelCase
+        class << self
+          #
+          # Checks attribute :camel_case option must be boolean
+          #
+          # @param opts [Hash] Attribute options
+          #
+          # @raise [SeregaError] Attribute validation error
+          #
+          # @return [void]
+          #
+          def call(opts)
+            camel_case_option_exists = opts.key?(:camel_case)
+            return unless camel_case_option_exists
+
+            value = opts[:camel_case]
+            return if value.equal?(true) || value.equal?(false)
+
+            raise SeregaError, "Attribute option :camel_case must have a boolean value, but #{value.class} was provided"
+          end
+        end
+      end
+
+      # CamelCase config object
+      class CamelCaseConfig
+        attr_reader :opts
+
+        #
+        # Initializes CamelCaseConfig object
+        #
+        # @param opts [Hash] camel_case plugin options
+        # @option opts [#call] :transform Callable object that transforms original attribute name
+        #
+        # @return [Serega::SeregaPlugins::CamelCase::CamelCaseConfig] CamelCaseConfig object
+        #
+        def initialize(opts)
+          @opts = opts
+        end
+
+        # @return [#call] defined object that transforms name
+        def transform
+          opts.fetch(:transform)
+        end
+
+        # Sets transformation callable object
+        #
+        # @param value [#call] transformation
+        #
+        # @return [#call] camel_case plugin transformation callable object
+        def transform=(value)
+          raise SeregaError, "Transform value must respond to #call" unless value.respond_to?(:call)
+
+          params = value.is_a?(Proc) ? value.parameters : value.method(:call).parameters
+          if params.count != 1 || !params.all? { |param| (param[0] == :req) || (param[0] == :opt) }
+            raise SeregaError, "Transform value must respond to #call and accept 1 regular parameter"
+          end
+
+          opts[:transform] = value
+        end
+      end
+
+      #
+      # SeregaAttributeNormalizer additional/patched instance methods
+      #
+      # @see SeregaAttributeNormalizer::AttributeInstanceMethods
+      #
+      module AttributeNormalizerInstanceMethods
+        private
+
+        #
+        # Patch for original `prepare_name` method
+        #
+        # Makes camelCased name
+        #
+        def prepare_name
+          res = super
+          return res if init_opts[:camel_case] == false
+
+          self.class.serializer_class.config.camel_case.transform.call(res.to_s).to_sym
+        end
+      end
+    end
+
+    register_plugin(CamelCase.plugin_name, CamelCase)
+  end
+end

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

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    #
+    # Plugin :depth_limit
+    #
+    # Helps to secure from malicious queries that require to serialize too much
+    # or from accidental serializing of 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.
+    #
+    # Any class-level serialization methods also check depth limit as they also instantiate serializer.
+    #
+    # 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:
+    #
+    #   - config.depth_limit.limit
+    #   - config.depth_limit.limit=
+    #
+    # There are no default limit, but it should be set when enabling plugin.
+    #
+    # @example
+    #
+    #   class AppSerializer < Serega
+    #     plugin :depth_limit, limit: 10 # set limit for all child classes
+    #   end
+    #
+    #   class UserSerializer < AppSerializer
+    #     config.depth_limit.limit = 5 # overrides limit for UserSerializer
+    #   end
+    #
+    module DepthLimit
+      # @return [Symbol] Plugin name
+      def self.plugin_name
+        :depth_limit
+      end
+
+      #
+      # Applies plugin code to specific serializer
+      #
+      # @param serializer_class [Class<Serega>] Current serializer class
+      # @param _opts [Hash] Loaded plugins options
+      #
+      # @return [void]
+      #
+      def self.load_plugin(serializer_class, **_opts)
+        serializer_class::SeregaPlan.include(PlanInstanceMethods)
+        serializer_class::SeregaConfig.include(ConfigInstanceMethods)
+      end
+
+      #
+      # Adds config options and runs other callbacks after plugin was loaded
+      #
+      # @param serializer_class [Class<Serega>] Current serializer class
+      # @param opts [Hash] loaded plugins opts
+      #
+      # @return [void]
+      #
+      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`" }
+        config.opts[:depth_limit] = {}
+        config.depth_limit.limit = limit
+      end
+
+      # DepthLimit config object
+      class DepthLimitConfig
+        attr_reader :opts
+
+        #
+        # Initializes DepthLimitConfig object
+        #
+        # @param opts [Hash] depth_limit plugin options
+        #
+        # @return [SeregaPlugins::DepthLimit::DepthLimitConfig] DepthLimitConfig object
+        #
+        def initialize(opts)
+          @opts = opts
+        end
+
+        # @return [Integer] defined depth limit
+        def limit
+          opts.fetch(:limit)
+        end
+
+        #
+        # Set depth limit
+        #
+        # @param value [Integer] depth limit
+        #
+        # @return [Integer] depth limit
+        def limit=(value)
+          raise SeregaError, "Depth limit must be an Integer" unless value.is_a?(Integer)
+
+          opts[:limit] = value
+        end
+      end
+
+      #
+      # Serega::SeregaConfig additional/patched class methods
+      #
+      # @see Serega::SeregaConfig
+      #
+      module ConfigInstanceMethods
+        # @return [Serega::SeregaPlugins::DepthLimit::DepthLimitConfig] current depth_limit config
+        def depth_limit
+          @depth_limit ||= DepthLimitConfig.new(opts.fetch(:depth_limit))
+        end
+      end
+
+      #
+      # SeregaPlan additional/patched instance methods
+      #
+      # @see SeregaPlan
+      #
+      module PlanInstanceMethods
+        #
+        # Initializes serialization plan
+        # Overrides original method (adds depth_limit validation)
+        #
+        def initialize(parent_plan_point, *)
+          check_depth_limit_exceeded(parent_plan_point)
+          super
+        end
+
+        private
+
+        def check_depth_limit_exceeded(current_point)
+          plan = self
+          depth_level = 1
+          point = current_point
+
+          while point
+            depth_level += 1
+            plan = point.plan
+            point = plan.parent_plan_point
+          end
+
+          root_serializer = plan.class.serializer_class
+          root_depth_limit = root_serializer.config.depth_limit.limit
+
+          if depth_level > root_depth_limit
+            fields_chain = [current_point.name]
+            fields_chain << current_point.name while (current_point = current_point.plan.parent_plan_point)
+            details = "#{root_serializer} (depth limit: #{root_depth_limit}) -> #{fields_chain.reverse!.join(" -> ")}"
+            raise DepthLimitError.new("Depth limit was exceeded", details)
+          end
+        end
+      end
+    end
+
+    register_plugin(DepthLimit.plugin_name, DepthLimit)
+  end
+
+  #
+  # Special error for depth_limit plugin
+  #
+  class DepthLimitError < SeregaError
+    #
+    # Details of why depth limit error happens.
+    #
+    # @return [String] error details
+    #
+    attr_reader :details
+
+    #
+    # Initializes new error
+    #
+    # @param message [String] Error message
+    # @param details [String] Error additional details
+    #
+    # @return [DepthLimitError] error instance
+    #
+    def initialize(message, details = nil)
+      super(message)
+      @details = details
+    end
+  end
+end

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

@@ -40,7 +40,7 @@ class Serega
       # @return [void]
       #
       def self.load_plugin(serializer_class, **_opts)
-        require_relative "./validations/check_opt_many"
+        require_relative "validations/check_opt_many"
 
         serializer_class::CheckAttributeParams.include(CheckAttributeParamsInstanceMethods)
       end

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

@@ -56,10 +56,10 @@ class Serega
       # @return [void]
       #
       def self.load_plugin(serializer_class, **_opts)
-        require_relative "./validations/check_opt_if"
-        require_relative "./validations/check_opt_if_value"
-        require_relative "./validations/check_opt_unless"
-        require_relative "./validations/check_opt_unless_value"
+        require_relative "validations/check_opt_if"
+        require_relative "validations/check_opt_if_value"
+        require_relative "validations/check_opt_unless"
+        require_relative "validations/check_opt_unless_value"
 
         serializer_class::SeregaAttribute.include(SeregaAttributeInstanceMethods)
         serializer_class::SeregaPlanPoint.include(PlanPointInstanceMethods)

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

@@ -62,12 +62,12 @@ class Serega
         serializer_class.include(InstanceMethods)
         serializer_class::SeregaConfig.include(ConfigInstanceMethods)
 
-        require_relative "./meta_attribute"
-        require_relative "./validations/check_block"
-        require_relative "./validations/check_opt_hide_nil"
-        require_relative "./validations/check_opt_hide_empty"
-        require_relative "./validations/check_opts"
-        require_relative "./validations/check_path"
+        require_relative "meta_attribute"
+        require_relative "validations/check_block"
+        require_relative "validations/check_opt_hide_nil"
+        require_relative "validations/check_opt_hide_empty"
+        require_relative "validations/check_opts"
+        require_relative "validations/check_path"
 
         meta_attribute_class = Class.new(MetaAttribute)
         meta_attribute_class.serializer_class = serializer_class

data/lib/serega/plugins/preloads/lib/modules/attribute_normalizer.rb

@@ -36,7 +36,7 @@ class Serega
             if preloads_provided
               opts[:preload]
             elsif opts.key?(:serializer) && self.class.serializer_class.config.preloads.auto_preload_attributes_with_serializer
-              key
+              method_name
             elsif opts.key?(:delegate) && self.class.serializer_class.config.preloads.auto_preload_attributes_with_delegate
               opts[:delegate].fetch(:to)
             end

data/lib/serega/plugins/preloads/lib/preload_paths.rb

@@ -22,18 +22,25 @@ class Serega
           #
           # Transforms user provided preloads to array of paths
           #
-          # @param value [Array,Hash,String,Symbol,nil,false] preloads
+          # @param preloads [Array,Hash,String,Symbol,nil,false] association(s) to preload
           #
           # @return [Hash] preloads transformed to hash
           #
-          def call(preloads, path = [], result = [])
-            preloads = FormatUserPreloads.call(preloads)
+          def call(preloads)
+            formatted_preloads = FormatUserPreloads.call(preloads)
+            return FROZEN_EMPTY_ARRAY if formatted_preloads.empty?
 
-            preloads.each do |key, nested_preloads|
+            paths(formatted_preloads, [], [])
+          end
+
+          private
+
+          def paths(formatted_preloads, path, result)
+            formatted_preloads.each do |key, nested_preloads|
               path << key
               result << path.dup
 
-              call(nested_preloads, path, result)
+              paths(nested_preloads, path, result)
               path.pop
             end
 

data/lib/serega/plugins/preloads/lib/preloads_constructor.rb

@@ -11,7 +11,7 @@ class Serega
           #
           # Constructs preloads hash for given attributes plan
           #
-          # @param plan [Array<Serega::PlanPoint>] Serialization plan
+          # @param plan [Array<SeregaPlanPoint>] Serialization plan
           #
           # @return [Hash]
           #

data/lib/serega/plugins/preloads/preloads.rb

@@ -15,7 +15,7 @@ class Serega
     #
     # This options are very handy if you want to forget about finding preloads manually.
     #
-    # Preloads can be disabled with `preload: false` attribute option option.
+    # Preloads can be disabled with `preload: false` attribute option.
     # Also automatically added preloads can be overwritten with manually specified `preload: :another_value`.
     #
     # Some examples, **please read comments in the code below**
@@ -79,17 +79,17 @@ class Serega
       # @return [void]
       #
       def self.load_plugin(serializer_class, **_opts)
-        require_relative "./lib/format_user_preloads"
-        require_relative "./lib/modules/attribute"
-        require_relative "./lib/modules/attribute_normalizer"
-        require_relative "./lib/modules/check_attribute_params"
-        require_relative "./lib/modules/config"
-        require_relative "./lib/modules/plan_point"
-        require_relative "./lib/preload_paths"
-        require_relative "./lib/preloads_config"
-        require_relative "./lib/preloads_constructor"
-        require_relative "./validations/check_opt_preload"
-        require_relative "./validations/check_opt_preload_path"
+        require_relative "lib/format_user_preloads"
+        require_relative "lib/modules/attribute"
+        require_relative "lib/modules/attribute_normalizer"
+        require_relative "lib/modules/check_attribute_params"
+        require_relative "lib/modules/config"
+        require_relative "lib/modules/plan_point"
+        require_relative "lib/preload_paths"
+        require_relative "lib/preloads_config"
+        require_relative "lib/preloads_constructor"
+        require_relative "validations/check_opt_preload"
+        require_relative "validations/check_opt_preload_path"
 
         serializer_class.include(InstanceMethods)
         serializer_class::SeregaAttribute.include(AttributeInstanceMethods)

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

@@ -127,7 +127,7 @@ class Serega
         # @option opts [Symbol, String, nil] :one root for single-object serialization
         # @option opts [Symbol, String, nil] :many root for many-objects serialization
         #
-        # @return [Serega::SeregaPlugins::Root::RootConfig] RootConfig object
+        # @return [SeregaPlugins::Root::RootConfig] RootConfig object
         #
         def initialize(opts)
           @opts = opts

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

@@ -18,7 +18,7 @@ class Serega
       #
       def self.load_plugin(serializer_class, **_opts)
         serializer_class.include(InstanceMethods)
-        require_relative "./parse_string_modifiers"
+        require_relative "parse_string_modifiers"
       end
 
       #

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

@@ -26,7 +26,7 @@ class Serega
           private
 
           def check_usage_with_other_params(opts, block)
-            raise SeregaError, "Option :const can not be used together with option :key" if opts.key?(:key)
+            raise SeregaError, "Option :const can not be used together with option :method" if opts.key?(:method)
             raise SeregaError, "Option :const can not be used together with option :value" if opts.key?(:value)
             raise SeregaError, "Option :const can not be used together with block" if block
           end

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

@@ -32,8 +32,9 @@ class Serega
 
             delegate_opts = opts[:delegate]
             check_opt_delegate_to(delegate_opts)
-            check_opt_delegate_key(delegate_opts)
+            check_opt_delegate_method(delegate_opts)
             check_opt_delegate_allow_nil(delegate_opts)
+            check_opt_delegate_extra_opts(delegate_opts)
           end
 
           def check_opt_delegate_to(delegate_opts)
@@ -43,16 +44,20 @@ class Serega
             Utils::CheckOptIsStringOrSymbol.call(delegate_opts, :to)
           end
 
-          def check_opt_delegate_key(delegate_opts)
-            Utils::CheckOptIsStringOrSymbol.call(delegate_opts, :key)
+          def check_opt_delegate_method(delegate_opts)
+            Utils::CheckOptIsStringOrSymbol.call(delegate_opts, :method)
           end
 
           def check_opt_delegate_allow_nil(delegate_opts)
             Utils::CheckOptIsBool.call(delegate_opts, :allow_nil)
           end
 
+          def check_opt_delegate_extra_opts(delegate_opts)
+            Utils::CheckAllowedKeys.call(delegate_opts, %i[to method allow_nil], :delegate)
+          end
+
           def check_usage_with_other_params(opts, block)
-            raise SeregaError, "Option :delegate can not be used together with option :key" if opts.key?(:key)
+            raise SeregaError, "Option :delegate can not be used together with option :method" if opts.key?(:method)
             raise SeregaError, "Option :delegate can not be used together with option :const" if opts.key?(:const)
             raise SeregaError, "Option :delegate can not be used together with option :value" if opts.key?(:value)
             raise SeregaError, "Option :delegate can not be used together with block" if block

data/lib/serega/validations/attribute/{check_opt_key.rb → check_opt_method.rb}

@@ -4,12 +4,12 @@ class Serega
   module SeregaValidations
     module Attribute
       #
-      # Attribute `:key` option validator
+      # Attribute `:method` option validator
       #
-      class CheckOptKey
+      class CheckOptMethod
         class << self
           #
-          # Checks attribute :key option
+          # Checks attribute :method option
           #
           # @param opts [Hash] Attribute options
           #
@@ -18,18 +18,18 @@ class Serega
           # @return [void]
           #
           def call(opts, block = nil)
-            return unless opts.key?(:key)
+            return unless opts.key?(:method)
 
             check_usage_with_other_params(opts, block)
-            Utils::CheckOptIsStringOrSymbol.call(opts, :key)
+            Utils::CheckOptIsStringOrSymbol.call(opts, :method)
           end
 
           private
 
           def check_usage_with_other_params(opts, block)
-            raise SeregaError, "Option :key can not be used together with option :const" if opts.key?(:const)
-            raise SeregaError, "Option :key can not be used together with option :value" if opts.key?(:value)
-            raise SeregaError, "Option :key can not be used together with block" if block
+            raise SeregaError, "Option :method can not be used together with option :const" if opts.key?(:const)
+            raise SeregaError, "Option :method can not be used together with option :value" if opts.key?(:value)
+            raise SeregaError, "Option :method can not be used together with block" if block
           end
         end
       end

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

@@ -27,7 +27,7 @@ class Serega
           private
 
           def check_usage_with_other_params(opts, block)
-            raise SeregaError, "Option :value can not be used together with option :key" if opts.key?(:key)
+            raise SeregaError, "Option :value can not be used together with option :method" if opts.key?(:method)
             raise SeregaError, "Option :value can not be used together with option :const" if opts.key?(:const)
             raise SeregaError, "Option :value can not be used together with block" if block
           end

data/lib/serega/validations/check_attribute_params.rb

@@ -58,12 +58,12 @@ class Serega
         # - plugin :if (checks :if, :if_value, :unless, :unless_value options)
         # - plugin :preloads (checks :preload option)
         def check_opts
-          Utils::CheckAllowedKeys.call(opts, allowed_opts_keys)
+          Utils::CheckAllowedKeys.call(opts, allowed_opts_keys, :attribute)
 
           Attribute::CheckOptConst.call(opts, block)
           Attribute::CheckOptDelegate.call(opts, block)
           Attribute::CheckOptHide.call(opts)
-          Attribute::CheckOptKey.call(opts, block)
+          Attribute::CheckOptMethod.call(opts, block)
           Attribute::CheckOptMany.call(opts)
           Attribute::CheckOptSerializer.call(opts)
           Attribute::CheckOptValue.call(opts, block)

data/lib/serega/validations/check_initiate_params.rb

@@ -35,7 +35,7 @@ class Serega
         private
 
         def check_allowed_keys
-          Utils::CheckAllowedKeys.call(opts, serializer_class.config.initiate_keys)
+          Utils::CheckAllowedKeys.call(opts, serializer_class.config.initiate_keys, :initiate)
         end
 
         def check_modifiers

data/lib/serega/validations/check_serialize_params.rb

@@ -33,7 +33,7 @@ class Serega
         private
 
         def check_opts
-          Utils::CheckAllowedKeys.call(opts, serializer_class.config.serialize_keys)
+          Utils::CheckAllowedKeys.call(opts, serializer_class.config.serialize_keys, :serialize)
 
           Utils::CheckOptIsHash.call(opts, :context)
           Utils::CheckOptIsBool.call(opts, :many)

data/lib/serega/validations/utils/check_allowed_keys.rb

@@ -18,11 +18,13 @@ class Serega
         # @raise [Serega::SeregaError] error when any hash key is not allowed
         #
         # @return [void]
-        def self.call(opts, allowed_keys)
+        def self.call(opts, allowed_keys, parameter_name)
           opts.each_key do |key|
             next if allowed_keys.include?(key)
 
-            raise SeregaError, "Invalid option #{key.inspect}. Allowed options are: #{allowed_keys.map(&:inspect).join(", ")}"
+            raise SeregaError,
+              "Invalid #{parameter_name} option #{key.inspect}." \
+              " Allowed options are: #{allowed_keys.map(&:inspect).sort.join(", ")}"
           end
         end
       end

data/lib/serega.rb

@@ -32,8 +32,8 @@ require_relative "serega/validations/attribute/check_name"
 require_relative "serega/validations/attribute/check_opt_const"
 require_relative "serega/validations/attribute/check_opt_hide"
 require_relative "serega/validations/attribute/check_opt_delegate"
-require_relative "serega/validations/attribute/check_opt_key"
 require_relative "serega/validations/attribute/check_opt_many"
+require_relative "serega/validations/attribute/check_opt_method"
 require_relative "serega/validations/attribute/check_opt_serializer"
 require_relative "serega/validations/attribute/check_opt_value"
 require_relative "serega/validations/initiate/check_modifiers"
@@ -172,7 +172,20 @@ class Serega
       new(modifiers_opts).to_h(object, serialize_opts)
     end
 
-    # @see #call
+    #
+    # Serializes provided object to Hash
+    #
+    # @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)`)
+    #
+    # @return [Hash] Serialization result
+    #
     def to_h(object, opts = nil)
       call(object, opts)
     end
@@ -283,8 +296,17 @@ class Serega
     def initialize(opts = nil)
       @opts = (opts.nil? || opts.empty?) ? FROZEN_EMPTY_HASH : parse_modifiers(opts)
       self.class::CheckInitiateParams.new(@opts).validate if opts&.fetch(:check_initiate_params) { config.check_initiate_params }
+
+      @plan = self.class::SeregaPlan.call(@opts)
     end
 
+    #
+    # Plan for serialization.
+    # This plan can be traversed to find serialized attributes and nested attributes.
+    #
+    # @return [Serega::SeregaPlan] Serialization plan
+    attr_reader :plan
+
     #
     # Serializes provided object to Hash
     #
@@ -338,15 +360,6 @@ class Serega
       config.from_json.call(json)
     end
 
-    #
-    # Plan for serialization.
-    # This plan can be traversed to find serialized attributes and nested attributes.
-    #
-    # @return [Array<Serega::SeregaPlanPoint>] plan
-    def plan
-      @plan ||= self.class::SeregaPlan.call(opts)
-    end
-
     private
 
     attr_reader :opts

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: serega
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.16.0
 platform: ruby
 authors:
 - Andrey Glushkov
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-08-13 00:00:00.000000000 Z
+date: 2023-10-14 00:00:00.000000000 Z
 dependencies: []
 description: |
   JSON Serializer
@@ -58,7 +58,9 @@ files:
 - lib/serega/plugins/batch/lib/validations/check_batch_opt_key.rb
 - lib/serega/plugins/batch/lib/validations/check_batch_opt_loader.rb
 - lib/serega/plugins/batch/lib/validations/check_opt_batch.rb
+- lib/serega/plugins/camel_case/camel_case.rb
 - lib/serega/plugins/context_metadata/context_metadata.rb
+- lib/serega/plugins/depth_limit/depth_limit.rb
 - lib/serega/plugins/explicit_many_option/explicit_many_option.rb
 - lib/serega/plugins/explicit_many_option/validations/check_opt_many.rb
 - lib/serega/plugins/formatters/formatters.rb
@@ -99,8 +101,8 @@ files:
 - lib/serega/validations/attribute/check_opt_const.rb
 - lib/serega/validations/attribute/check_opt_delegate.rb
 - lib/serega/validations/attribute/check_opt_hide.rb
-- lib/serega/validations/attribute/check_opt_key.rb
 - lib/serega/validations/attribute/check_opt_many.rb
+- lib/serega/validations/attribute/check_opt_method.rb
 - lib/serega/validations/attribute/check_opt_serializer.rb
 - lib/serega/validations/attribute/check_opt_value.rb
 - lib/serega/validations/check_attribute_params.rb