serega 0.14.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f11821b5953500ef9f895ad8c96e97951734615363f3147c623b70519b6199a5
-  data.tar.gz: 8b03241a9def2e5a8777a75e61062f8b81544e497a1a1e490e085d52f14a326c
+  metadata.gz: b291b12115b8ca239642972b103f896f13f02874acdc5663a8f404e02673ca8d
+  data.tar.gz: 18bd88ca4bd77ca147161189efe57b2c544da6cc1b460fc7c694855d4b22edc9
 SHA512:
-  metadata.gz: eb5cb48e74c0e9c8307c6ceb6c47b918eb46ef3c160de90d0eb976239bbc036f1d3fb78219abd5567977f348e3e03d7e492e29140e6d85223fcf14289d794d89
-  data.tar.gz: acb7623ea317aab640aae70d0a5dfa0c436b706529741b36b15d938ab6af7523576f72ab4633b591b61dcdc38df768818eab3811005c248c3a00d2872cdccc46
+  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,78 +892,86 @@ Look at [select serialized fields](#selecting-fields) for `:hide` usage examples
  end
 ```
 
-### Plugin :openapi
+### 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
 
-Helps to build OpenAPI schemas
+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 schemas can be easily used with [rswag](https://github.com/rswag/rswag#referenced-parameters-and-schema-definitions)"
-gem by adding them to "config.swagger_docs"
+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.
 
-Schemas properties will have no any "type" or other limits specified by default,
-you should provide them as new attribute `:openapi` option.
+You can provide your own callable transformation when defining plugin,
+for example `plugin :camel_case, transform: ->(name) { name.camelize }`
 
-This plugin adds type "object" or "array" only for relationships and marks
-attributes as **required** if they have no `:hide` option set
-(manually or automatically).
+For any attribute camelCase-behavior can be skipped when
+`camel_case: false` attribute option provided.
 
-After enabling this plugin attributes with :serializer option will have
-to have `:many` option set to construct "object" or "array" openapi
-property type.
+This plugin transforms only attribute keys,
+without affecting `root`, `metadata`, `context_metadata` plugins keys.
 
-- constructing all serializers schemas:
-  `Serega::OpenAPI.schemas`
-- constructing specific serializers schemas:
-  `Serega::OpenAPI.schemas(Serega::OpenAPI.serializers - [MyBaseSerializer])`
-- constructing one serializer schema:
-  `SomeSerializer.openapi_schema`
+If you wish to [select serialized fields](#selecting-fields), you should
+provide them camelCased.
 
 ```ruby
-  class BaseSerializer < Serega
-    plugin :openapi
-  end
+class AppSerializer < Serega
+  plugin :camel_case
+end
 
-  class UserSerializer < BaseSerializer
-    attribute :name, openapi: { type: "string" }
+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
 
-    openapi_properties(
-      name: { type: :string }
-    )
-  end
+require "ostruct"
+user = OpenStruct.new(first_name: "Bruce", last_name: "Wayne")
+UserSerializer.to_h(user)
+# => {firstName: "Bruce", lastName: "Wayne", full_name: "Bruce Wayne"}
 
-  class PostSerializer < BaseSerializer
-    attribute :text, openapi: { type: "string" }
-    attribute :user, serializer: UserSerializer, many: false
-    attribute :comments, serializer: PostSerializer, many: true, hide: true
+UserSerializer.new(only: %i[firstName lastName]).to_h(user)
+# => {firstName: "Bruce", lastName: "Wayne"}
+```
 
-    openapi_properties(
-      text: { type: :string },
-      user: { type: 'object' }, # `$ref` added automatically
-      comments: { type: 'array' } # `items` option with `$ref` added automatically
-    )
-  end
+### 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=`
 
-  puts Serega::OpenAPI.schemas
-  # =>
-  # {
-  #   "PostSerializer" => {
-  #     type: "object",
-  #     properties: {
-  #       text: {type: "string"},
-  #       user: {:$ref => "#/components/schemas/UserSerializer"},
-  #       comments: {type: "array", items: {:$ref => "#/components/schemas/PostSerializer"}}
-  #     },
-  #     required: [:text, :comments],
-  #     additionalProperties: false
-  #   },
-  #   "UserSerializer" => {
-  #     type: "object",
-  #     properties: {
-  #       name: {type: "string"}
-  #     },
-  #     required: [:name],
-  #     additionalProperties: false
-  #   }
-  # }
+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
@@ -967,12 +979,9 @@ property type.
 Plugin requires to add :many option when adding relationships
 (relationships are attributes with :serializer option specified)
 
-Adding this plugin makes clearer to find if relationship returns array or single
+Adding this plugin makes it clearer to find if relationship returns array or single
 object
 
-Also plugin `:openapi` load this plugin automatically as it need to know if
-relationship is array
-
 ```ruby
   class BaseSerializer < Serega
     plugin :explicit_many_option
@@ -1018,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.14.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)