serega 0.39.0 → 0.40.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a223242ae8bce14755fa2cbb444ff78728d95fccb0ce3077c212706e39e4ddcc
-  data.tar.gz: b8e1d3bdf11a57091cfd22eb31bb017979382df4b2166b05f746d064dc486f6e
+  metadata.gz: edecae0c35540be687e394092e3b0a158fa1c2aeff4710ff5ce8e17effba1eb2
+  data.tar.gz: 7e63d238aad501f31be388824bb6b594e9f7988e17c49e4fc478d9353993c63b
 SHA512:
-  metadata.gz: d815a4a17625533c34659451851c33806bd4d1e0bf862945b2118d52315726184322c55d989378cf8ac7f9b4d04a392dfa344af196491b984ddc1d094d15c063
-  data.tar.gz: ecf2be1cff661bfe8e99103748276969f72442b04b8308dd136d137dc88f28dfb543ad73a5e0880a31eb6f6c4a6a51e6ccab307a92f867551ff4b19b56d38f73
+  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.
 
 ---
 
@@ -26,6 +27,7 @@ It has some great features:
   keeping the code dry
 - Conditional attributes - ([if][if] plugin)
 - Auto camelCase keys - [camel_case][camel_case] plugin
+- Serializing Hash records - [hash_access][hash_access] attribute option
 
 ## Installation
 
@@ -74,8 +76,9 @@ class UserSerializer < Serega
   # Regular attribute
   attribute :first_name
 
-  # Option :method specifies the method that must be called on the
-  # serialized object
+  # Option :method specifies the name used to read the attribute's value —
+  # a method called on the serialized object by default, or a Hash key when
+  # combined with :hash_access
   attribute :first_name, method: :old_first_name
 
   # Attribute blocks below require a base serializer for nested serializers.
@@ -494,6 +497,12 @@ class AppSerializer < Serega
   #   proc { |object, batches:| batches[:counter][object.id] }
   config.batch_id_option = :id
 
+  # Defaults for the `hash_access:` attribute option — `default_mode` is
+  # what `hash_access: true` (and a Hash form omitting :mode) resolves to.
+  # See "Serializing Hash records".
+  config.hash_access.default_mode = :symbol # the default
+  config.hash_access.default_allow_missing_key = false # the default
+
   # Parent class for nested serializers defined with attribute blocks.
   # Usually a settings-only serializer, e.g. `config.base_serializer = self`
   # in an application base serializer class. There is no default — an
@@ -664,6 +673,69 @@ end
 
 ---
 
+## Serializing Hash records
+
+(objects should implement `#[]`, `#fetch`, and `#key?` - Hash already has them)
+
+The `hash_access: <mode>` attribute option makes an attribute read its value from
+Hash keys instead of calling a method.
+
+Allowed `<mode>`:
+
+- `:symbol` reads record[:name]
+- `:string` reads record["name"]
+- `true` shorthand for `config.hash_access.default_mode` (`:symbol` by default)
+
+By default missing keys will raise `KeyError`.
+
+`config.hash_access.default_allow_missing_key = true` will change `KeyError`
+to return `nil` value instead. `config.hash_access.default_mode = <mode>`
+changes what `true` (and a Hash form omitting `:mode`) resolves to.
+
+```ruby
+class UserSerializer < Serega
+  config.hash_access.default_mode = :symbol             # the default
+  config.hash_access.default_allow_missing_key = true    # false by default
+
+  attribute :name, hash_access: true     # reads record[:name] (config.hash_access.default_mode)
+  attribute :name, hash_access: :symbol  # reads record[:name]
+  attribute :name, hash_access: :string  # reads record["name"]
+
+  # Use long form if you need to override `allow_missing_key`
+  attribute :name, hash_access: { allow_missing_key: false }
+  attribute :name, hash_access: { mode: :symbol, allow_missing_key: false }
+  attribute :name, hash_access: { mode: :string, allow_missing_key: false }
+end
+```
+
+Delegated attributes configure hash access **per step**:
+
+- `to_hash_access` configures reading `<mode>` for intermediate object
+- `hash_access` configures reading `<mode>` for final key
+
+```ruby
+# reads `record.address.city` (no hash access)
+attribute :city, delegate: { to: :address } # record.address.city
+
+# reads record.address[:city]
+attribute :city, delegate: { to: :address, hash_access: :symbol }
+
+# reads record[:address].city
+attribute :city, delegate: { to: :address, to_hash_access: :symbol }
+
+# reads record[:address][:city]
+attribute :city, delegate: { to: :address, to_hash_access: :symbol, hash_access: :symbol }
+
+# reads record["address"] and if exists returns record["address"][:city]
+attribute :city,
+  delegate: {
+    to: :address,
+    allow_nil: true,
+    to_hash_access: { mode: :string, allow_missing_key: true },
+    hash_access: { mode: :symbol, allow_missing_key: false }
+  }
+```
+
 ## Plugins
 
 ### Plugin :activerecord_preloads
@@ -678,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:
 
@@ -715,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]
@@ -804,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.
@@ -828,41 +899,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
 ```
@@ -924,12 +993,11 @@ callables keep receiving the raw objects.
 
 ### Plugin :string_modifiers
 
-Allows to specify modifiers as strings.
+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.
 
-Serialized attributes must be split with `,` and nested attributes must be
-defined inside brackets `()`.
-
-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
@@ -937,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.
+Adds `:if`, `:unless`, `:if_value`, `:unless_value` attribute options to
+conditionally remove attributes from the response.
 
-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.
@@ -987,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:
-
-- adding a `:first_name` key to the resulting hash
-- adding a `#first_name` method call result as value
-
-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`
+Without this plugin, responding with *camelCased* keys means specifying the
+attribute name and method directly for each attribute:
+`attribute :firstName, method: first_name`
 
-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.
+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.
 
-You can provide custom transformation when adding the plugin,
-for example `plugin :camel_case, transform: ->(name) { name.camelize }`
+Provide a 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.
@@ -1069,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 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
@@ -1128,6 +1182,7 @@ The gem is available as open source under the terms of the [MIT License](https:/
 [context_metadata]: #plugin-context_metadata
 [depth_limit]: #plugin-depth_limit
 [formatters]: #plugin-formatters
+[hash_access]: #serializing-hash-records
 [metadata]: #plugin-metadata
 [preloads]: #preloads
 [presenter]: #plugin-presenter

data/VERSION

@@ -1 +1 @@
-0.39.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
@@ -254,7 +256,10 @@ class Serega
       end
 
       def prepare_keyword_block
-        AttributeValueResolvers::KeywordResolver.get(method_name)
+        mode, allow_nil = hash_access
+        return AttributeValueResolvers::KeywordResolver.get(method_name) unless mode
+
+        AttributeValueResolvers::HashAccessResolver.get(method_name, mode, allow_nil)
       end
 
       def prepare_batch_loader_block
@@ -291,15 +296,68 @@ class Serega
         init_opts.fetch(:default) { many ? FROZEN_EMPTY_ARRAY : nil }
       end
 
+      # `delegate: {to_hash_access: ...}` configures hash access for the
+      # intermediate (:to) read, `delegate: {hash_access: ...}` for the
+      # final (:method) read. A step without its sub-option keeps a plain
+      # method read.
       def prepare_delegate_block
         delegate = init_opts[:delegate]
         return unless delegate
 
         key_method_name = delegate[:method] || method_name
         delegate_to = delegate[:to]
+        delegate_allow_nil = delegate.fetch(:allow_nil) { config.delegate_default_allow_nil }
+
+        to_access = delegate[:to_hash_access]
+        final_access = delegate[:hash_access]
+        unless to_access || final_access
+          return AttributeValueResolvers::DelegateResolver.get(delegate_to, key_method_name, delegate_allow_nil)
+        end
+
+        to_step = delegate_to_step(delegate_to, to_access)
+        final_step = delegate_final_step(key_method_name, final_access)
+        AttributeValueResolvers::HashAccessDelegateResolver.get(to_step, final_step, delegate_allow_nil)
+      end
+
+      def delegate_to_step(delegate_to, access)
+        return AttributeValueResolvers::Keyword.new(delegate_to) unless access
+
+        mode, allow_missing_key = parse_hash_access(access)
+        AttributeValueResolvers::HashAccessKeyword.new(delegate_to, mode, allow_missing_key)
+      end
+
+      def delegate_final_step(key_method_name, access)
+        return AttributeValueResolvers::Keyword.new(key_method_name) unless access
 
-        allow_nil = delegate.fetch(:allow_nil) { config.delegate_default_allow_nil }
-        AttributeValueResolvers::DelegateResolver.get(delegate_to, key_method_name, allow_nil)
+        mode, allow_missing_key = parse_hash_access(access)
+        AttributeValueResolvers::HashAccessKeyword.new(key_method_name, mode, allow_missing_key)
+      end
+
+      # Resolves the :hash_access option of plain attributes
+      # @return [Array(Symbol, Boolean), nil] mode and allow_missing_key pair,
+      #   or nil when hash access is not enabled for this attribute
+      def hash_access
+        option = init_opts[:hash_access]
+        return unless option
+
+        parse_hash_access(option)
+      end
+
+      # Resolves a :hash_access value (`true`, a Symbol mode or a
+      # `{mode:, allow_missing_key:}` Hash) into a mode and allow_missing_key
+      # pair. `true` and a Hash omitting :mode resolve to
+      # `config.hash_access.default_mode`.
+      def parse_hash_access(option)
+        defaults = config.hash_access
+
+        case option
+        when true then [defaults.default_mode, defaults.default_allow_missing_key]
+        when Symbol then [option, defaults.default_allow_missing_key]
+        else
+          mode = option.fetch(:mode) { defaults.default_mode }
+          allow_missing_key = option.fetch(:allow_missing_key) { defaults.default_allow_missing_key }
+          [mode, allow_missing_key]
+        end
       end
 
       # Prepares preloads for this attribute.

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