serega 0.40.1 → 0.41.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: edecae0c35540be687e394092e3b0a158fa1c2aeff4710ff5ce8e17effba1eb2
-  data.tar.gz: 7e63d238aad501f31be388824bb6b594e9f7988e17c49e4fc478d9353993c63b
+  metadata.gz: 4d54f033e70155c517c02d15cd9a4eb5399e385b0ffdd68d8c6c2b390201a007
+  data.tar.gz: 23257bef39a343bea74c063f452fa1feed58738c454e467838cceb2fecdbe862
 SHA512:
-  metadata.gz: 506607362308145ffcc0a34474d76d8b0a0edb7fbb570deb1fb973c71c396aab65a1b7b408069d31c8a5e15f8c8146316f835194c53e4a68315fe62eb4992421
-  data.tar.gz: 6d5b5ebe921a36b197b4829721af89eb92f5e47522101d126cffc8c72e30ad2679a6f9084df2685cf2250d772c5b0974b76861260b2eb19c6f53660fba16f5d4
+  metadata.gz: 2a0df718af2b8f019af2fe9dc8bb82dc21a03631a211ecc00a3fd4e83d6ed3324505727c9124975181869fd11fb452e7670a060ae7e04eddd161186e3353366f
+  data.tar.gz: e5bc125a847e929bdaeb7ce044adbb4e866324d702032ee19abd76208949f406b166f4ecf111453d0f7130aa3dfb7d36e3269010df8adc7e05c50eba3c3a52cd

data/README.md

@@ -19,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)
@@ -29,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
@@ -463,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.
@@ -592,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

data/VERSION

@@ -1 +1 @@
-0.40.1
+0.41.0

data/lib/serega/plugins/root/root.rb

@@ -229,6 +229,8 @@ class Serega
         # @return [Data, Array<Data>, nil] Serialization result as Data object(s)
         #
         def to_data(object, opts = nil)
+          opts = normalize_serialization_opts(opts)
+          object = prepare_objects(object, opts[:context])
           opts = prepare_initial_serialization_opts(object, opts)
           serialized_data = serialize(object, opts)
           self.class::SeregaDataBuilder.call(self, serialized_data, opts)

data/lib/serega.rb

@@ -265,6 +265,63 @@ class Serega
       @preload_with = handler
     end
 
+    #
+    # Registers (or returns) the handler that replaces the serialized objects
+    # before serialization starts.
+    #
+    # The handler is called once per serialization with the objects provided to
+    # `.call`/`.to_h`/`.to_data` and the serialization context. Its result is
+    # serialized instead of the provided objects, which allows to accept ids or
+    # other references and load the records in one place.
+    #
+    # The handler runs before the `:many` option is detected, so it may turn a
+    # single object into a collection and back. A provided `:many` serialization
+    # option is still used as is.
+    #
+    # The handler runs only for the serialized objects, and not for objects of
+    # nested serializers.
+    #
+    # @example with a block
+    #   prepare_initial_objects { |user_ids| User.where(id: user_ids) }
+    #
+    # @example with a context
+    #   prepare_initial_objects { |user_ids, ctx| User.where(id: user_ids, account: ctx[:account]) }
+    #
+    # @example with a keyword context
+    #   prepare_initial_objects { |user_ids, ctx:| User.where(id: user_ids, account: ctx[:account]) }
+    #
+    # @example with a callable value
+    #   prepare_initial_objects UsersLoader
+    #
+    # @param value [#call, nil] Handler accepting (objects), (objects, context) or (objects, ctx:)
+    # @param block [Proc] Handler accepting (objects), (objects, context) or (objects, ctx:)
+    #
+    # @return [#call, nil] The registered handler
+    #
+    def prepare_initial_objects(value = nil, &block)
+      return @prepare_initial_objects if value.nil? && block.nil?
+      raise SeregaError, "prepare_initial_objects accepts a single callable or a block, not both" if value && block
+
+      handler = value || block
+      raise SeregaError, "prepare_initial_objects value must be a Proc or respond to #call" if !handler.is_a?(Proc) && !handler.respond_to?(:call)
+
+      signature = SeregaUtils::MethodSignature.call(handler, pos_limit: 2, keyword_args: [:ctx])
+      raise SeregaError, prepare_initial_objects_signature_error unless %w[1 2 1_ctx].include?(signature)
+
+      @prepare_initial_objects_signature = signature
+      @prepare_initial_objects = handler
+    end
+
+    #
+    # Signature of the registered prepare_initial_objects handler
+    #
+    # @return [String, nil] Handler signature
+    #
+    # @private
+    def prepare_initial_objects_signature
+      @prepare_initial_objects_signature
+    end
+
     #
     # Serializes provided object to Hash
     #
@@ -386,8 +443,20 @@ class Serega
       # Assign same preload handler
       subclass.preload_with(preload_with) if preload_with
 
+      # Assign same initial objects handler
+      subclass.prepare_initial_objects(prepare_initial_objects) if prepare_initial_objects
+
       super
     end
+
+    def prepare_initial_objects_signature_error
+      <<~ERR.strip
+        prepare_initial_objects handler arguments should have one of this signatures:
+        - (objects)        # one argument
+        - (objects, ctx)   # two arguments
+        - (objects, ctx:)  # one argument and one :ctx keyword argument
+      ERR
+    end
   end
 
   #
@@ -436,6 +505,8 @@ class Serega
     # @return [Hash] Serialization result
     #
     def call(object, opts = nil)
+      opts = normalize_serialization_opts(opts)
+      object = prepare_objects(object, opts[:context])
       opts = prepare_initial_serialization_opts(object, opts)
       serialize(object, opts)
     end
@@ -458,6 +529,8 @@ class Serega
     # @return [Data] Serialization result
     #
     def to_data(object, opts = nil)
+      opts = normalize_serialization_opts(opts)
+      object = prepare_objects(object, opts[:context])
       opts = prepare_initial_serialization_opts(object, opts)
       serialized_data = serialize(object, opts)
       self.class::SeregaDataBuilder.call(self, serialized_data)
@@ -488,11 +561,26 @@ class Serega
       SeregaUtils::ToHash.call(value)
     end
 
-    def prepare_initial_serialization_opts(object, opts)
+    def normalize_serialization_opts(opts)
       opts = opts ? opts.transform_keys(&:to_sym) : {}
       self.class::CheckSerializeParams.new(opts).validate unless opts.empty?
 
       opts[:context] ||= {}
+      opts
+    end
+
+    def prepare_objects(objects, context)
+      handler = self.class.prepare_initial_objects
+      return objects unless handler
+
+      case self.class.prepare_initial_objects_signature
+      when "1" then handler.call(objects)
+      when "2" then handler.call(objects, context)
+      else handler.call(objects, ctx: context) # "1_ctx"
+      end
+    end
+
+    def prepare_initial_serialization_opts(object, opts)
       opts[:level_queue] = SeregaEngine::LevelQueue.new
       opts[:many] = SeregaUtils::CollectionDetector.call(object) unless opts.key?(:many)
       opts[:plan] = plan

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: serega
 version: !ruby/object:Gem::Version
-  version: 0.40.1
+  version: 0.41.0
 platform: ruby
 authors:
 - Andrey