serega 0.40.0 → 0.40.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42da0ff66dc5eeb282fbb72144f78bcfc8ded1aa8609122ded10093f6c83dd96
-  data.tar.gz: f9fb2a2628756540cd08a5449a21883b0cf28ec45db8f461ee0944fd0f3812e9
+  metadata.gz: edecae0c35540be687e394092e3b0a158fa1c2aeff4710ff5ce8e17effba1eb2
+  data.tar.gz: 7e63d238aad501f31be388824bb6b594e9f7988e17c49e4fc478d9353993c63b
 SHA512:
-  metadata.gz: 1355573b7cb8d30ffbf844be46c03c4a5233fa9c190fa5e03fd39c0d1a396b9f7a19e7e2d4cf3afbd0445cd1d8dfc8ebbd1df6d77d91d338c0ede561c836fb99
-  data.tar.gz: 90ccd454b970598f9921ec1a6c9feab325a373d5628f884515141d34a3a72e7012273e37aa903046e064876f92bd956783ef3a9b93732ee23a8bcc8bec154ee3
+  metadata.gz: 506607362308145ffcc0a34474d76d8b0a0edb7fbb570deb1fb973c71c396aab65a1b7b408069d31c8a5e15f8c8146316f835194c53e4a68315fe62eb4992421
+  data.tar.gz: 6d5b5ebe921a36b197b4829721af89eb92f5e47522101d126cffc8c72e30ad2679a6f9084df2685cf2250d772c5b0974b76861260b2eb19c6f53660fba16f5d4

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 Andrey Glushkov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -4,7 +4,8 @@
 [![GitHub Actions][build-badge]][build]
 
 The Serega Ruby Serializer provides easy and powerful DSL to describe your
-objects and serialize them to Hash or JSON.
+objects and serialize them to Hash, ready for further conversion to JSON or
+other formats.
 
 ---
 
@@ -749,31 +750,38 @@ handler; to use a different ORM, register your own instead.
 ```ruby
 class AppSerializer < Serega
   config.auto_preload = true
-  config.hide_by_default = false
-
   plugin :activerecord_preloads
 end
 
+class AlbumSerializer < AppSerializer
+  # no preloads
+  attribute :title
+
+  # preloads :downloads, as manually specified
+  attribute :downloads_count, preload: :downloads, value: proc { |album| album.downloads.count }
+end
+
 class UserSerializer < AppSerializer
+  # no preloads
   attribute :username
+
+  # preloads :user_stats, as auto_preload is enabled for :delegate attributes
   attribute :comments_count, delegate: { to: :user_stats }
-  attribute :albums, serializer: AlbumSerializer
-end
 
-class AlbumSerializer < AppSerializer
-  attribute :title
-  attribute :downloads_count, preload: :downloads,
-    value: proc { |album| album.downloads.count }
+  # preloads :albums, as auto_preload is enabled for :serializer attributes
+  attribute :albums, serializer: AlbumSerializer
 end
 
-UserSerializer.to_h(user)
-# preloads :user_stats and :albums on the user; the AlbumSerializer level
-# preloads :downloads on the albums
+UserSerializer.to_h(users)
+# 1 query to load :user_stats for all users
+# + 1 query to load :albums for all users
+# + 1 query to load :downloads for all albums
+# = 3 queries total, regardless of how many users/albums are serialized
 ```
 
 ### Plugin :root
 
-Allows to add root key to your serialized data
+Adds a root key to serialized data.
 
 Accepts options:
 
@@ -786,56 +794,47 @@ Adds additional config options:
 - config.root.one
 - config.root.many
 - config.root.one=
-- config.root_many=
+- config.root.many=
 
 The default root is `:data`.
 
-The root key can be changed per serialization.
-
 ```ruby
- # @example Change root per serialization:
+class UserSerializer < Serega
+  plugin :root # default root is :data
+end
 
- class UserSerializer < Serega
-   plugin :root
- end
+class UserSerializer < Serega
+  plugin :root, root: :users
+end
 
- UserSerializer.to_h(nil)              # => {:data=>nil}
- UserSerializer.to_h(nil, root: :user) # => {:user=>nil}
- UserSerializer.to_h(nil, root: nil)   # => nil
-```
+class UserSerializer < Serega
+  plugin :root, root_one: :user, root_many: :people
+end
 
-The root key can be removed for all responses by providing the `root: nil`
-plugin option.
+class UserSerializer < Serega
+  plugin :root, root: nil # no root key by default
+end
+```
 
-In this case, no root key will be added. But it still can be added manually.
+The root key can also be changed per serialization, or removed entirely by
+providing `root: nil` (it can still be added back per serialization).
 
 ```ruby
- #@example Define :root plugin with different options
-
- class UserSerializer < Serega
-   plugin :root # default root is :data
- end
-
- class UserSerializer < Serega
-   plugin :root, root: :users
- end
-
- class UserSerializer < Serega
-   plugin :root, root_one: :user, root_many: :people
- end
+class UserSerializer < Serega
+  plugin :root
+end
 
- class UserSerializer < Serega
-   plugin :root, root: nil # no root key by default
- end
+UserSerializer.to_h(nil)              # => {:data=>nil}
+UserSerializer.to_h(nil, root: :user) # => {:user=>nil}
+UserSerializer.to_h(nil, root: nil)   # => nil
 ```
 
 ### Plugin :metadata
 
 Depends on: [`:root`][root] plugin, that must be loaded first
 
-Adds ability to describe metadata and adds it to serialized response
-
-Adds class-level `.meta_attribute` method. It accepts:
+Adds metadata to the serialized response via the class-level `meta_attribute`
+method, which accepts:
 
 - `*path` [Array of Symbols] - nested hash keys.
 - `**options` [Hash]
@@ -875,7 +874,8 @@ AppSerializer.to_h(nil)
 
 Depends on: [`:root`][root] plugin, that must be loaded first
 
-Allows to provide metadata and attach it to serialized response.
+Adds metadata supplied per serialization call (as opposed to `:metadata`,
+which is defined statically on the serializer).
 
 Accepts option `:context_metadata_key` with the name of the root metadata keyword.
 By default, it has the `:meta` value.
@@ -899,41 +899,39 @@ UserSerializer.to_h(nil, meta: { version: '1.0.1' })
 
 ### Plugin :formatters
 
-Allows to define `formatters` and apply them to attribute values.
+Defines named value formatters once and applies them to any attribute.
 
-Config option `config.formatters.add` can be used to add formatters.
+Use `config.formatters.add()` to register formatters. The `:format`
+attribute option then accepts a formatter name or a callable directly.
 
-Attribute option `:format` can be used with the name of formatter or with
-callable instance.
-
-Formatters can accept up to 2 parameters (formatted object, context)
+Formatters receive up to 2 parameters: the value and the context.
 
 ```ruby
 class AppSerializer < Serega
   plugin :formatters, formatters: {
-    iso8601: ->(value) { time.iso8601.round(6) },
+    iso8601: ->(value) { value.iso8601 },
     on_off: ->(value) { value ? 'ON' : 'OFF' },
-    money: ->(value, ctx) { value / 10**ctx[:digits) }
+    money: ->(value) { value.round(2) },
     date: DateTypeFormatter # callable
   }
 end
 
 class UserSerializer < Serega
-  # Additionally, we can add formatters via config in subclasses
+  # Additionally we can add formatters via config in subclasses
   config.formatters.add(
-    iso8601: ->(value) { time.iso8601.round(6) },
+    iso8601: ->(value) { value.iso8601 },
     on_off: ->(value) { value ? 'ON' : 'OFF' },
     money: ->(value) { value.round(2) }
   )
 
   # Using predefined formatter
   attribute :commission, format: :money
-  attribute :is_logined, format: :on_off
+  attribute :is_logged_in, format: :on_off
   attribute :created_at, format: :iso8601
   attribute :updated_at, format: :iso8601
 
   # Using `callable` formatter
-  attribute :score_percent, format: PercentFormmatter # callable class
+  attribute :score_percent, format: PercentFormatter # callable class
   attribute :score_percent, format: proc { |percent| "#{percent.round(2)}%" }
 end
 ```
@@ -995,12 +993,11 @@ callables keep receiving the raw objects.
 
 ### Plugin :string_modifiers
 
-Allows to specify modifiers as strings.
-
-Serialized attributes must be split with `,` and nested attributes must be
-defined inside brackets `()`.
+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.
 
-Modifiers can still be provided the old way using nested hashes or arrays.
+Modifiers can still be provided the old way, as nested hashes or arrays.
 
 ```ruby
 PostSerializer.plugin :string_modifiers
@@ -1008,25 +1005,19 @@ PostSerializer.new(only: "id,user(id,username)").to_h(post)
 PostSerializer.new(except: "user(username,email)").to_h(post)
 PostSerializer.new(with: "user(email)").to_h(post)
 
-# Modifiers can still be provided the old way using nested hashes or arrays.
 PostSerializer.new(with: {user: %i[email, username]}).to_h(post)
 ```
 
 ### Plugin :if
 
-Plugin adds `:if, :unless, :if_value, :unless_value` options to
-attributes so we can remove attributes from the response in various ways.
-
-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 getting the final value.
-
-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.
+Adds `:if`, `:unless`, `:if_value`, `:unless_value` attribute options to
+conditionally remove attributes from the response.
 
-Options `:if_value` and `:unless_value` cannot be used with the `:serializer` option.
-Use `:if` and `:unless` in this case.
+`: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.
 
 See also a `:hide` option that is available without any plugins to hide
 attribute without conditions.
@@ -1058,24 +1049,18 @@ Look at [select serialized fields](#selecting-fields) for `:hide` usage examples
 
 ### Plugin :camel_case
 
-By default, when we add an attribute like `attribute :first_name` it means:
+Without this plugin, responding with *camelCased* keys means specifying the
+attribute name and method directly for each attribute:
+`attribute :firstName, method: first_name`
 
-- adding a `:first_name` key to the resulting hash
-- adding a `#first_name` method call result as value
+This plugin camelCases every attribute name automatically, replacing `_x`
+with `X` throughout the string. The transformation runs once, when the
+attribute is defined, not on every serialization.
 
-But it's often desired to respond with *camelCased* keys.
-By default, this can be achieved by specifying the attribute name and method directly
-for each attribute: `attribute :firstName, method: first_name`
+Provide a custom transformation when adding the plugin, for example
+`plugin :camel_case, transform: ->(name) { name.camelize }`
 
-This plugin transforms all attribute names automatically.
-We use a simple regular expression to replace `_x` with `X` for the whole string.
-We make this transformation only once when the attribute is defined.
-
-You can provide custom transformation when adding the plugin,
-for example `plugin :camel_case, transform: ->(name) { name.camelize }`
-
-For any attribute camelCase-behavior can be skipped when
-the `camel_case: false` attribute option provided.
+Skip camelCase for a single attribute with `camel_case: false`.
 
 This plugin transforms only attribute keys, without affecting the `root`,
 `metadata` and `context_metadata` plugins keys.
@@ -1140,27 +1125,25 @@ end
 
 ### Plugin :explicit_many_option
 
-The plugin requires adding a `:many` option when adding relationships
-(attributes with the `:serializer` option or a block defining a nested
-serializer).
-
-Adding this plugin makes it clearer to find if some relationship is an array or
-a single object.
+Requires the `:many` option on every relationship attribute (an attribute
+with the `:serializer` option or a block defining a nested serializer), so
+it's always explicit whether it returns one object or many.
 
 ```ruby
-  class BaseSerializer < Serega
-    plugin :explicit_many_option
-  end
+class BaseSerializer < Serega
+  plugin :explicit_many_option
+  config.base_serializer = self
+end
 
-  class UserSerializer < BaseSerializer
+class PostSerializer < BaseSerializer
+  attribute :text
+
+  attribute :user, many: false do
     attribute :name
   end
 
-  class PostSerializer < BaseSerializer
-    attribute :text
-    attribute :user, serializer: UserSerializer, many: false
-    attribute :comments, serializer: PostSerializer, many: true
-  end
+  attribute :comments, serializer: PostSerializer, many: true
+end
 ```
 
 ## Errors

data/VERSION

@@ -1 +1 @@
-0.40.0
+0.40.1

data/lib/serega/attribute.rb

@@ -4,10 +4,12 @@ class Serega
   #
   # Stores serialized attribute data
   #
+  # @private
   class SeregaAttribute
     #
     # Attribute instance methods
     #
+    # @private
     module AttributeInstanceMethods
       # Attribute initial params
       # @return [Hash] Attribute initial params

data/lib/serega/attribute_normalizer.rb

@@ -4,10 +4,12 @@ class Serega
   #
   # Prepares provided attribute options
   #
+  # @private
   class SeregaAttributeNormalizer
     #
     # AttributeNormalizer instance methods
     #
+    # @private
     module AttributeNormalizerInstanceMethods
       # Attribute initial params
       # @return [Hash] Attribute initial params

data/lib/serega/attribute_value_resolvers/batch.rb

@@ -4,10 +4,12 @@ class Serega
   #
   # Attribute value resolvers
   #
+  # @private
   module AttributeValueResolvers
     #
     # Builds value resolver class for attributes with :batch option
     #
+    # @private
     class BatchResolver
       #
       # Generates callable block to find attribute value when attribute with :batch
@@ -55,6 +57,7 @@ class Serega
     #
     # Builds value resolver class for attributes with :batch option
     #
+    # @private
     class Batch
       def initialize(loader_name, id_method)
         @loader_name = loader_name

data/lib/serega/attribute_value_resolvers/const.rb

@@ -4,10 +4,12 @@ class Serega
   #
   # Attribute value resolvers
   #
+  # @private
   module AttributeValueResolvers
     #
     # Builds value resolver class for attributes with :const option
     #
+    # @private
     class ConstResolver
       #
       # Creates resolver that returns constant value
@@ -23,6 +25,7 @@ class Serega
     #
     # Value resolver class for attributes with :const option
     #
+    # @private
     class Const
       def initialize(const_value)
         @const_value = const_value

data/lib/serega/attribute_value_resolvers/delegate.rb

@@ -4,10 +4,12 @@ class Serega
   #
   # Attribute value resolvers
   #
+  # @private
   module AttributeValueResolvers
     #
     # Builds value resolver class for attributes with :delegate option
     #
+    # @private
     class DelegateResolver
       #
       # Creates resolver that delegates method call to another object
@@ -25,6 +27,7 @@ class Serega
     #
     # Value resolver class for attributes with :delegate (with :allow_nil) option
     #
+    # @private
     class DelegateAllowNil
       def initialize(delegate_to, method_name)
         @delegate_to = delegate_to
@@ -49,6 +52,7 @@ class Serega
     #
     # Value resolver class for attributes with :delegate (without :allow_nil) option
     #
+    # @private
     class Delegate
       def initialize(delegate_to, method_name)
         @delegate_to = delegate_to

data/lib/serega/attribute_value_resolvers/hash_access.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
 class Serega
+  # @private
   module AttributeValueResolvers
     #
     # Builds value resolver for attributes with the :hash_access option
     #
+    # @private
     class HashAccessResolver
       # Allowed hash access modes
       MODES = %i[symbol string].freeze
@@ -27,6 +29,7 @@ class Serega
     # Builds value resolver for attributes with the :delegate option using
     # hash access on any of its steps
     #
+    # @private
     class HashAccessDelegateResolver
       #
       # Creates resolver that delegates through the provided step readers
@@ -45,6 +48,7 @@ class Serega
     #
     # Value resolver for attributes with the :hash_access option
     #
+    # @private
     class HashAccessKeyword
       def initialize(name, mode, allow_missing_key)
         @key = (mode == :symbol) ? name.to_sym : name.to_s
@@ -72,6 +76,7 @@ class Serega
     #
     # Value resolver for attributes with :hash_access and :delegate (without :allow_nil) options
     #
+    # @private
     class HashAccessDelegate
       def initialize(to_step, final_step)
         @to_step = to_step
@@ -92,6 +97,7 @@ class Serega
     #
     # Value resolver for attributes with :hash_access and :delegate (with :allow_nil) options
     #
+    # @private
     class HashAccessDelegateAllowNil
       def initialize(to_step, final_step)
         @to_step = to_step

data/lib/serega/attribute_value_resolvers/keyword.rb

@@ -4,10 +4,12 @@ class Serega
   #
   # Attribute value resolvers
   #
+  # @private
   module AttributeValueResolvers
     #
     # Builds value resolver class for attributes with :keyword option
     #
+    # @private
     class KeywordResolver
       #
       # Creates resolver that calls method on object
@@ -23,6 +25,7 @@ class Serega
     #
     # Value resolver class for attributes with :keyword option
     #
+    # @private
     class Keyword
       def initialize(keyword)
         @keyword = keyword

data/lib/serega/data_builder.rb

@@ -5,8 +5,10 @@ class Serega
   # Builds Data objects from serialized hashes.
   # Used by `#to_data` / `.to_data`.
   #
+  # @private
   class SeregaDataBuilder
     # SeregaDataBuilder class methods
+    # @private
     module SeregaDataBuilderClassMethods
       #
       # Converts serialized Hash/Array result into a tree of Ruby Data objects

data/lib/serega/engine/level.rb

@@ -4,6 +4,7 @@ class Serega
   #
   # Batch feature main module
   #
+  # @private
   module SeregaEngine
     #
     # One serialization level: all objects serialized under a single plan and the
@@ -12,6 +13,7 @@ class Serega
     # or preload runs once over the whole set. A deeper level (its own plan) loads
     # separately.
     #
+    # @private
     class Level
       # @param serializer [SeregaObjectSerializer] serializer that resolves this level
       def initialize(serializer)

data/lib/serega/engine/level_queue.rb

@@ -4,6 +4,7 @@ class Serega
   #
   # Batch feature main module
   #
+  # @private
   module SeregaEngine
     #
     # Level-order queue of serialization levels for one serialization run.
@@ -15,6 +16,7 @@ class Serega
     # Processing level-by-level lets a named batch loader and preloads run once per
     # level over all of its objects.
     #
+    # @private
     class LevelQueue
       def initialize
         @levels = []

data/lib/serega/engine/loader.rb

@@ -4,14 +4,17 @@ class Serega
   #
   # Batch feature main module
   #
+  # @private
   module SeregaEngine
     #
     #  Batch loader
     #
+    # @private
     class Loader
       #
       # BatchLoader instance methods
       #
+      # @private
       module InstanceMethods
         # BatchLoader initial params
         # @return [Hash] BatchLoader initial params

data/lib/serega/helpers/serializer_class_helper.rb

@@ -4,10 +4,12 @@ class Serega
   #
   # Helpers
   #
+  # @private
   module SeregaHelpers
     #
     # Stores link to current serializer class
     #
+    # @private
     module SerializerClassHelper
       # Shows serializer class current class is namespaced under
       # @return [Class<Serega>] Serializer class that current class is namespaced under.

data/lib/serega/object_serializer.rb

@@ -9,10 +9,12 @@ class Serega
   # which resolves every attribute for every object and enqueues child levels for
   # relations.
   #
+  # @private
   class SeregaObjectSerializer
     #
     # SeregaObjectSerializer instance methods
     #
+    # @private
     module InstanceMethods
       attr_reader :context, :plan, :many, :opts, :level_queue
 

data/lib/serega/plan.rb

@@ -5,10 +5,12 @@ class Serega
   # Constructs plan - list of serialized attributes.
   # We will traverse this plan to construct serialized response.
   #
+  # @private
   class SeregaPlan
     #
     # SeregaPlan class methods
     #
+    # @private
     module ClassMethods
       #
       # Constructs plan of attributes that should be serialized.
@@ -68,6 +70,7 @@ class Serega
     #
     # SeregaPlan instance methods
     #
+    # @private
     module InstanceMethods
       # Parent plan point
       # @return [SeregaPlanPoint, nil]

data/lib/serega/plan_point.rb

@@ -4,10 +4,12 @@ class Serega
   #
   # Combines attribute and nested attributes
   #
+  # @private
   class SeregaPlanPoint
     #
     # SeregaPlanPoint instance methods
     #
+    # @private
     module InstanceMethods
       # Link to current plan this point belongs to
       # @return [SeregaAttribute] Current plan