serega 0.40.0 → 0.41.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42da0ff66dc5eeb282fbb72144f78bcfc8ded1aa8609122ded10093f6c83dd96
-  data.tar.gz: f9fb2a2628756540cd08a5449a21883b0cf28ec45db8f461ee0944fd0f3812e9
+  metadata.gz: 4d54f033e70155c517c02d15cd9a4eb5399e385b0ffdd68d8c6c2b390201a007
+  data.tar.gz: 23257bef39a343bea74c063f452fa1feed58738c454e467838cceb2fecdbe862
 SHA512:
-  metadata.gz: 1355573b7cb8d30ffbf844be46c03c4a5233fa9c190fa5e03fd39c0d1a396b9f7a19e7e2d4cf3afbd0445cd1d8dfc8ebbd1df6d77d91d338c0ede561c836fb99
-  data.tar.gz: 90ccd454b970598f9921ec1a6c9feab325a373d5628f884515141d34a3a72e7012273e37aa903046e064876f92bd956783ef3a9b93732ee23a8bcc8bec154ee3
+  metadata.gz: 2a0df718af2b8f019af2fe9dc8bb82dc21a03631a211ecc00a3fd4e83d6ed3324505727c9124975181869fd11fb452e7670a060ae7e04eddd161186e3353366f
+  data.tar.gz: e5bc125a847e929bdaeb7ce044adbb4e866324d702032ee19abd76208949f406b166f4ecf111453d0f7130aa3dfb7d36e3269010df8adc7e05c50eba3c3a52cd

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.
 
 ---
 
@@ -18,6 +19,7 @@ It has some great features:
 - Secure from malicious queries with [depth_limit][depth_limit] plugin
 - Solutions for N+1 problem (via built-in [batch loading](#batch-loading), [preloads][preloads] or
   [activerecord_preloads][activerecord_preloads] plugin)
+- Load serialized objects by ids ([prepare_initial_objects](#prepare-initial-objects))
 - Built-in object presenter ([presenter][presenter] plugin)
 - Adding custom metadata (via [metadata][metadata] or
   [context_metadata][context_metadata] plugins)
@@ -28,10 +30,51 @@ It has some great features:
 - Auto camelCase keys - [camel_case][camel_case] plugin
 - Serializing Hash records - [hash_access][hash_access] attribute option
 
+## Table of Contents
+
+<!-- toc -->
+
+- [Installation](#installation)
+- [Usage](#usage)
+   - [Define serializers](#define-serializers)
+   - [Adding attributes](#adding-attributes)
+   - [Defining a nested serializer with a block](#defining-a-nested-serializer-with-a-block)
+   - [Serializing](#serializing)
+   - [Selecting Fields](#selecting-fields)
+   - [Using Context](#using-context)
+   - [Batch Loading](#batch-loading)
+   - [Prepare Initial Objects](#prepare-initial-objects)
+- [Configuration](#configuration)
+- [Preloads](#preloads)
+   - [Serializing the same object in association](#serializing-the-same-object-in-association)
+   - [Custom preloading](#custom-preloading)
+- [Serializing Hash records](#serializing-hash-records)
+- [Plugins](#plugins)
+   - [Plugin :activerecord_preloads](#plugin-activerecord_preloads)
+   - [Plugin :root](#plugin-root)
+   - [Plugin :metadata](#plugin-metadata)
+   - [Plugin :context_metadata](#plugin-context_metadata)
+   - [Plugin :formatters](#plugin-formatters)
+   - [Plugin :presenter](#plugin-presenter)
+   - [Plugin :string_modifiers](#plugin-string_modifiers)
+   - [Plugin :if](#plugin-if)
+   - [Plugin :camel_case](#plugin-camel_case)
+   - [Plugin :depth_limit](#plugin-depth_limit)
+   - [Plugin :explicit_many_option](#plugin-explicit_many_option)
+- [Errors](#errors)
+- [Release](#release)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
+<!-- tocstop -->
+
 ## Installation
 
 `bundle add serega`
 
+## Usage
+
 ### Define serializers
 
 Most apps should define **base serializer** with common plugins and settings to
@@ -462,6 +505,77 @@ class UserSerializer < Serega
 end
 ```
 
+### Prepare Initial Objects
+
+`prepare_initial_objects` replaces the serialized objects before serialization
+starts, so a serializer can accept ids or other references and load the records
+itself.
+
+```ruby
+class UserSerializer < Serega
+  # OccamsRecord returns read-only records — faster and with a much lower
+  # memory footprint than ActiveRecord models
+  prepare_initial_objects { |user_ids| OccamsRecord.query(User.where(id: user_ids)).run }
+
+  attribute :first_name
+end
+
+UserSerializer.to_h(["17", "42"]) # => [{first_name: "Ann"}, {first_name: "Bob"}]
+```
+
+The handler accepts the serialization context as a second positional or a
+`:ctx` keyword argument, and can be provided as a callable value:
+
+```ruby
+class UserSerializer < Serega
+  prepare_initial_objects { |ids, ctx| OccamsRecord.query(User.where(id: ids, account: ctx[:account])).run }
+  # or
+  prepare_initial_objects { |ids, ctx:| OccamsRecord.query(User.where(id: ids, account: ctx[:account])).run }
+  # or
+  prepare_initial_objects UsersLoader
+end
+```
+
+The handler runs once per serialization, before the `:many` option is detected,
+so it can turn a single object into a collection and back:
+
+```ruby
+class UserSerializer < Serega
+  prepare_initial_objects { |user_id| OccamsRecord.query(User.where(id: user_id)).run }
+
+  attribute :first_name
+end
+
+UserSerializer.to_h("17") # => [{first_name: "Ann"}] - an array, as the handler returned a collection
+```
+
+A provided `:many` option is used as is. A handler returning `nil` serializes
+`nil`, and errors raised inside the handler are not wrapped.
+
+Declared preloads are applied to the prepared objects, so the handler pairs
+with [preloads][preloads] and the
+[activerecord_preloads][activerecord_preloads] plugin:
+
+```ruby
+class UserSerializer < Serega
+  plugin :activerecord_preloads
+
+  prepare_initial_objects { |user_ids| User.where(id: user_ids) }
+
+  attribute :albums_count, preload: :albums, value: proc { |user| user.albums.size }
+end
+```
+
+⚠️ The `:preload` option needs ActiveRecord objects. When the handler returns
+anything else — OccamsRecord read-only records, Structs, Hashes, plain objects
+— preloading raises `Serega::SeregaError` (`Can't preload ... to ...`) during
+serialization. Load that data with [batch loading](#batch-loading) instead,
+which works with any objects.
+
+The handler runs for the serialized objects only, and not for objects of nested
+serializers. It is inherited by subclasses, so declare it on concrete
+serializers rather than on a base serializer shared by all of them.
+
 ## Configuration
 
 Here are the default options. Other options can be added with plugins.
@@ -591,7 +705,7 @@ end
 
 ---
 
-### SPECIFIC CASE: Serializing the same object in association
+### Serializing the same object in association
 
 For example, you show your current user as "user" and use the same user object
 to serialize "user_stats". `UserStatSerializer` relies on user fields and any
@@ -749,31 +863,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 +907,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 +987,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 +1012,39 @@ UserSerializer.to_h(nil, meta: { version: '1.0.1' })
 
 ### Plugin :formatters
 
-Allows to define `formatters` and apply them to attribute values.
-
-Config option `config.formatters.add` can be used to add formatters.
+Defines named value formatters once and applies them to any attribute.
 
-Attribute option `:format` can be used with the name of formatter or with
-callable instance.
+Use `config.formatters.add()` to register formatters. The `:format`
+attribute option then accepts a formatter name or a callable directly.
 
-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 +1106,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 +1118,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.
+Adds `:if`, `:unless`, `:if_value`, `:unless_value` attribute options to
+conditionally remove attributes from the response.
 
-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.
-
-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 +1162,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:
-
-- adding a `:first_name` key to the resulting hash
-- adding a `#first_name` method call result as value
+Without this plugin, responding with *camelCased* keys means specifying the
+attribute name and method directly for each attribute:
+`attribute :firstName, method: first_name`
 
-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`
+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.
 
-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.
+Provide a custom transformation when adding the plugin, for example
+`plugin :camel_case, transform: ->(name) { name.camelize }`
 
-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 +1238,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 PostSerializer < BaseSerializer
+  attribute :text
 
-  class UserSerializer < BaseSerializer
+  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.41.0

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