serega 0.38.0 → 0.40.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 384da177845e2385a0100d23147cea0034860b148cd46738dc3d6ec7ea7d7eda
-  data.tar.gz: f08d482a83cb0cde30ae4c03e924f50be6aaabea24d76564bc47a7a1eadf4f98
+  metadata.gz: 42da0ff66dc5eeb282fbb72144f78bcfc8ded1aa8609122ded10093f6c83dd96
+  data.tar.gz: f9fb2a2628756540cd08a5449a21883b0cf28ec45db8f461ee0944fd0f3812e9
 SHA512:
-  metadata.gz: c9f2f95d8a74ce4951f7acef89a1cf603fcba2f15af50d246f85d58e1456b06c03b749fef620c741f8e2482999c6f7471fb5dff9a904b275f79f039999ab7fdc
-  data.tar.gz: 69c1b8f898f81317310e875a8771db096b3d4613b34769024d66fe801554e53094fd59e3cfea923ef81bb5d837a31ef28ceadc825003c95a4a2340f6b0b0bf74
+  metadata.gz: 1355573b7cb8d30ffbf844be46c03c4a5233fa9c190fa5e03fd39c0d1a396b9f7a19e7e2d4cf3afbd0445cd1d8dfc8ebbd1df6d77d91d338c0ede561c836fb99
+  data.tar.gz: 90ccd454b970598f9921ec1a6c9feab325a373d5628f884515141d34a3a72e7012273e37aa903046e064876f92bd956783ef3a9b93732ee23a8bcc8bec154ee3

data/README.md

@@ -26,6 +26,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,12 +75,29 @@ 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
 
-  # Block is used to define attribute value
-  attribute(:first_name) { |user| user.profile&.first_name }
+  # Attribute blocks below require a base serializer for nested serializers.
+  # See the "Defining a nested serializer with a block" section below.
+  config.base_serializer = Serega
+
+  # Method :itself is handy to serialize the same object with a nested set of
+  # attributes. Note: with the :presenter plugin the serialized value will be
+  # the Presenter instance itself; use `method: :__getobj__` to serialize the
+  # original unwrapped object instead.
+  attribute :statistics, method: :itself do
+    attribute :likes_count
+    attribute :comments_count
+  end
+
+  # Block defines a nested serializer for the attribute value.
+  # See the "Defining a nested serializer with a block" section below.
+  attribute :author do
+    attribute :name
+  end
 
   # Option :value can be used with a Proc or callable object to define
   # attribute value
@@ -114,13 +132,13 @@ class UserSerializer < Serega
 
   # Option `:many` specifies a has_many relationship. It is optional.
   # If not specified, it is defined during serialization by checking
-  # `object.is_a?(Enumerable)`
+  # `object.is_a?(Enumerable) && !object.is_a?(Hash) && !object.is_a?(Struct)`
   # Also the `:many` changes the default value from `nil` to `[]`.
   attribute :posts, serializer: PostSerializer, many: true
 
   # Option `:preload` allows to specify associations to preload to
   # attribute value
-  attribute(:email, preload: :emails) { |user| user.emails.find(&:verified?) }
+  attribute :email, preload: :emails, value: proc { |user| user.emails.find(&:verified?) }
 
   # Options `:if, :unless, :if_value and :unless_value` can be specified
   # when `:if` plugin is enabled. They hide the attribute key and value from the
@@ -139,6 +157,70 @@ class UserSerializer < Serega
 end
 ```
 
+### Defining a nested serializer with a block
+
+An attribute block defines an anonymous nested serializer. The attribute value
+is found as usual — by the attribute name or the `:method`, `:value`,
+`:delegate`, `:batch` option — and is serialized by this nested serializer.
+
+The nested serializer is a regular subclass of an explicitly chosen **base
+serializer** — usually a settings-only serializer holding your plugins and
+configuration. Choose it with the `base_serializer:` attribute option or the
+`config.base_serializer` setting (attribute option wins; an error is raised
+when none is set):
+
+```ruby
+class AppSerializer < Serega
+  plugin :activerecord_preloads
+
+  # Nested serializers defined with attribute blocks will inherit from
+  # AppSerializer
+  config.base_serializer = self
+end
+
+class UserSerializer < AppSerializer
+  attribute :first_name
+
+  # Serializes user.author with a nested serializer inherited from AppSerializer
+  attribute :author do
+    attribute :name
+  end
+
+  # Serializes the user itself, exposing only counters
+  attribute :statistics, method: :itself, base_serializer: StatsBaseSerializer do
+    attribute :likes_count
+    attribute :comments_count
+  end
+end
+
+UserSerializer.to_h(user)
+# => {first_name: "Bruce", author: {name: "Bob"}, statistics: {likes_count: 10, comments_count: 3}}
+```
+
+The nested serializer inherits everything the base serializer has — plugins,
+config, attributes, batch loaders, the preload handler — through the regular
+inheritance mechanism. Any serializer can be used as a base: if it has
+attributes, they are serialized by the nested serializer too, together with
+the attributes defined in the block. Anything the base does not provide can
+be declared inside the block:
+
+```ruby
+attribute :statistics, method: :itself do
+  batch(:stats) { |users| Stats.for_users(users) } # => { user_id => stat }
+
+  attribute :likes_count, batch: :stats, value: proc { |user, batches:| batches[:stats][user.id].likes }
+end
+```
+
+Things to keep in mind:
+
+- The nested serializer is created at the moment the attribute is defined.
+  Changes made to the base serializer later do not affect already defined
+  nested serializers.
+- Errors raised while serializing nested attributes are reported with a
+  readable serializer label, for example:
+  `(when serializing 'comments_count' attribute in UserSerializer.<statistics>)`.
+
 ### Serializing
 
 We can serialize objects using class method `.call` aliased as `.to_h` and
@@ -183,15 +265,6 @@ serializer.to_h(user1)
 serializer.to_h(user2)
 ```
 
----
-⚠️ When you serialize the `Struct` object, specify manually `many: false`. As Struct
-is Enumerable and we check `object.is_a?(Enumerable)` to detect if we should
-return array.
-
-```ruby
-UserSerializer.to_h(user_struct, many: false)
-```
-
 ### Selecting Fields
 
 By default, all attributes are serialized (except marked as `hide: true`).
@@ -312,9 +385,9 @@ current_user or any.
 
 ```ruby
 class UserSerializer < Serega
-  attribute(:email) do |user, ctx|
+  attribute :email, value: proc { |user, ctx|
     user.email if ctx[:current_user] == user
-  end
+  }
 end
 
 user = OpenStruct.new(email: 'email@example.com')
@@ -339,15 +412,18 @@ class UserSerializer < Serega
   batch :comments_count, ->(users) { Comment.where(user: users).group(:user_id).count }
   batch :comments_count, CommentsCountLoader # Example with callable class
 
-  # Full attribute example
-  attribute :comments_count, batch: { use: :comments_count },
-    value: proc { |user, batch:| batch[:comments_count][user.id] }
+  # Use a loader by its name
+  attribute :comments_count, batch: :comments_count
 
-  # Shorter version
-  attribute :comments_count, batch: { use: :comments_count, id: :id } # Equivalent, id: :id is default
+  # Equivalent — when the attribute name matches the loader name
+  attribute :comments_count, batch: true
 
-  # Shortest version
-  attribute :comments_count, batch: true # Equivalent
+  # Equivalent — the default value resolution spelled out
+  attribute :comments_count, batch: :comments_count,
+    value: proc { |user, batches:| batches[:comments_count][user.id] }
+
+  # Hash form — needed only for sub-options, for example a custom `:id` method
+  attribute :comments_count, batch: { use: :comments_count, id: :uuid }
 end
 ```
 
@@ -382,7 +458,7 @@ class UserSerializer < Serega
   # Summarize likes
   attribute :likes_count,
     batch: { use: [:facebook_likes, :twitter_likes] },
-    value: { |user, batch:| batch[:facebook_likes][user.id] + batch[:twitter_likes][user.id] }
+    value: proc { |user, batches:| batches[:facebook_likes][user.id] + batches[:twitter_likes][user.id] }
 end
 ```
 
@@ -390,6 +466,13 @@ end
 
 Here are the default options. Other options can be added with plugins.
 
+⚠️ Attributes are prepared at the moment they are defined. If a config option
+influences attributes (`auto_preload`, `hide_by_default`, `batch_id_option`,
+formatters, etc.), changing it affects only attributes defined **after** the
+change — including nested serializers defined with attribute blocks, which
+are created at their definition point. Configure the serializer before
+defining attributes.
+
 ```ruby
 class AppSerializer < Serega
   # With `activerecord_preloads` plugin it automatically adds `preload` option
@@ -413,6 +496,19 @@ 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
+  # attribute block raises an error when no base serializer is chosen (it can
+  # also be provided per-attribute with the `base_serializer:` option).
+  config.base_serializer = self
+
   # Disable/enable validation of modifiers (`:with, :except, :only`)
   # By default, this validation is enabled.
   # After disabling, all requested incorrect attributes will be skipped.
@@ -576,6 +672,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
@@ -793,7 +952,7 @@ class UserSerializer < Serega
 end
 ```
 
-With the plugin, they move into a clean class:
+With the plugin, they move into a `presenter do ... end` block:
 
 ```ruby
 class UserSerializer < Serega
@@ -802,7 +961,7 @@ class UserSerializer < Serega
   attribute :name
   attribute :role
 
-  class Presenter
+  presenter do
     def name
       [first_name, last_name].compact.join(' ')
     end
@@ -814,6 +973,9 @@ class UserSerializer < Serega
 end
 ```
 
+The block is evaluated inside the serializer's own `Presenter` class, so
+multiple `presenter` blocks accumulate.
+
 `Presenter` inherits from `SimpleDelegator`, so every method of the serialized
 object is available directly inside presenter methods. Any method not explicitly
 defined on `Presenter` is resolved via `method_missing` on the first call, which
@@ -825,6 +987,12 @@ The original wrapped object is accessible via `__getobj__` (standard
 
 The serialization context is accessible via the private method `__ctx__`.
 
+Objects are wrapped in the `Presenter` only when the serializer's `Presenter`
+class (or an inherited one) actually defines custom methods. Loading the
+plugin in a base serializer adds no overhead to serializers that don't
+customize their presenters — their attribute values, batch loaders and value
+callables keep receiving the raw objects.
+
 ### Plugin :string_modifiers
 
 Allows to specify modifiers as strings.
@@ -973,7 +1141,8 @@ end
 ### Plugin :explicit_many_option
 
 The plugin requires adding a `:many` option when adding relationships
-(attributes with the `:serializer` option).
+(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.
@@ -1030,6 +1199,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.38.0
+0.40.0

data/lib/serega/attribute.rb

@@ -45,10 +45,10 @@ class Serega
       # @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)
+      # @option opts [Boolean] :many Specifies has_many relationship. By default is detected via object.is_a?(Enumerable) && !object.is_a?(Hash) && !object.is_a?(Struct)
       # @option opts [Proc, #call] :value Custom block or callable to find attribute value
       # @option opts [Serega, Proc] :serializer Relationship serializer class. Use `proc { MySerializer }` if serializers have cross references
-      # @param block [Proc] Custom block to find attribute value
+      # @param block [Proc] Defines attributes of a nested anonymous serializer
       #
       def initialize(name:, opts: {}, block: nil)
         serializer_class = self.class.serializer_class
@@ -88,7 +88,7 @@ class Serega
       # @return [Object] Serialized attribute value
       #
       def value(object, context, batches: nil)
-        # Signatires should match allowed signatures in CheckOptValue and CheckBlock
+        # Signatures should match allowed signatures in CheckOptValue
         result =
           case value_block_signature
           when "1" then value_block.call(object)

data/lib/serega/attribute_normalizer.rb

@@ -133,8 +133,7 @@ class Serega
       end
 
       def prepare_value_block
-        init_block \
-          || init_opts[:value] \
+        init_opts[:value] \
           || prepare_const_block \
           || prepare_delegate_block \
           || prepare_batch_loader_block \
@@ -175,7 +174,73 @@ class Serega
       end
 
       def prepare_serializer
-        init_opts[:serializer]
+        block = init_block
+        return init_opts[:serializer] unless block
+
+        prepare_block_serializer(block)
+      end
+
+      # Builds an anonymous nested serializer from the attribute block.
+      #
+      # The serializer is a regular subclass of an explicitly chosen base —
+      # the :base_serializer attribute option or `config.base_serializer` —
+      # so it inherits everything the base has: plugins, config, attributes,
+      # batch loaders, the preload handler. Nested values can be any objects,
+      # which is why the base is chosen explicitly instead of inheriting from
+      # the current serializer. Its `inspect` is overridden to
+      # `CurrentSerializer.<attribute_name>` so error messages and debugging
+      # output point back to the defining attribute.
+      # Guards against cyclic definitions before building: inheriting the base
+      # serializer copies its attributes, and copying a block attribute builds
+      # its nested serializer — meeting the same block again while it is being
+      # built means the base serializer (transitively) contains the block
+      # attribute being built, so inheriting from it would recurse forever.
+      # The "in progress" mark is kept on the block itself — its identity is
+      # what defines the cycle (the same Proc object is shared by all copies
+      # of the attribute).
+      def prepare_block_serializer(block)
+        if block.instance_variable_defined?(:@serega_building_nested_serializer)
+          raise SeregaError,
+            "Can not define a nested serializer for attribute :#{name} —" \
+            " its base serializer #{block_base_serializer.inspect} (transitively)" \
+            " contains this same block attribute (cyclic definition)"
+        end
+
+        block.instance_variable_set(:@serega_building_nested_serializer, true)
+        begin
+          build_block_serializer(block)
+        ensure
+          block.remove_instance_variable(:@serega_building_nested_serializer)
+        end
+      end
+
+      def build_block_serializer(block)
+        label = "#{self.class.serializer_class.inspect}.<#{name}>"
+
+        serializer = Class.new(block_base_serializer) do
+          define_singleton_method(:inspect) { label }
+          define_singleton_method(:to_s) { label }
+          instance_exec(&block)
+        end
+
+        # An empty nested serializer means the block was intended as an
+        # old-style value block — raise the explaining error.
+        raise SeregaError, SeregaValidations::Attribute::CheckBlock::ERROR_MESSAGE if serializer.attributes.empty?
+
+        serializer
+      end
+
+      # Base class for the nested serializer. Must be chosen explicitly —
+      # usually a settings-only serializer holding plugins and configuration
+      # (e.g. `config.base_serializer = self` in an application base class).
+      def block_base_serializer
+        base_serializer = init_opts[:base_serializer] || config.base_serializer
+        return base_serializer if base_serializer
+
+        raise SeregaError,
+          "Attribute block requires a base serializer for the nested serializer." \
+          " Provide the `base_serializer: <SerializerClass>` attribute option" \
+          " or set `config.base_serializer = <SerializerClass>`"
       end
 
       def prepare_method_name
@@ -189,7 +254,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
@@ -226,15 +294,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
 
-        allow_nil = delegate.fetch(:allow_nil) { config.delegate_default_allow_nil }
-        AttributeValueResolvers::DelegateResolver.get(delegate_to, key_method_name, allow_nil)
+        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
+
+        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.
@@ -250,16 +371,26 @@ class Serega
 
         # Auto-preload the delegated association
         if config.auto_preload.fetch(:has_delegate_option) && init_opts[:delegate]
-          return init_opts[:delegate][:to]
+          return auto_preload_value(init_opts[:delegate][:to])
         end
 
         # Auto-preload the nested serializer's association
-        if config.auto_preload.fetch(:has_serializer_option) && init_opts[:serializer] && !init_opts.key?(:batch)
-          return method_name
+        # (a block defines a nested serializer, same as the :serializer option)
+        if config.auto_preload.fetch(:has_serializer_option) && (init_opts[:serializer] || init_block) && !init_opts.key?(:batch)
+          return auto_preload_value(method_name)
         end
 
         nil
       end
+
+      # Skips auto-preloading of methods that return the serialized object
+      # itself (:itself by default) — they are not associations,
+      # so preloading them would fail or make no sense.
+      def auto_preload_value(preload_method)
+        return nil if config.auto_preload_excluded_methods.include?(preload_method.to_sym)
+
+        preload_method
+      end
     end
 
     extend Serega::SeregaHelpers::SerializerClassHelper

data/lib/serega/attribute_value_resolvers/batch.rb

@@ -18,6 +18,7 @@ class Serega
       # It handles this cases:
       # - `attribute :foo, batch: true`
       # - `attribute :foo, batch: FooLoader`
+      # - `attribute :foo, batch: :foo_loader`
       # - `attribute :foo, batch: { id: :foo_id }`
       # - `attribute :foo, batch: { use: FooLoader, id: foo_id }`
       # - `attribute :foo, batch: { use: :foo_loader, id: foo_id }`
@@ -32,6 +33,9 @@ class Serega
           serializer_class.batch(attribute_name, batch_opt)
           batch_name = attribute_name
           batch_id_method = default_method
+        elsif batch_opt.is_a?(Symbol) || batch_opt.is_a?(String) # ex: `batch: :foo_loader`
+          batch_name = batch_opt.to_sym
+          batch_id_method = default_method
         else
           use = batch_opt[:use]
           batch_id_method = batch_opt[:id] || default_method