serega 0.42.0 → 0.50.0

data/lib/serega/source_group.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+class Serega
+  #
+  # All sources that one plan serializes in one run, for example the posts of
+  # all users. A source is an object to serialize. A serialized object is its
+  # output: a Hash, Struct or Data object.
+  #
+  # The group serializes its sources in two steps:
+  # - `#discover` runs the preloads, reads the relation sources and adds one
+  #   child group per relation.
+  # - `#build` builds the serialized objects. It runs after the child groups
+  #   are built, thus the relation values are ready.
+  #
+  class SeregaSourceGroup # :nodoc:
+    # Serialization run
+    attr_reader :run
+
+    # Serialization plan
+    attr_reader :plan
+
+    # Serialization context
+    attr_reader :context
+
+    # Sources (or their presenters)
+    attr_reader :sources
+
+    # Serialized object of each
+    # source, after #build
+    attr_reader :serialized
+
+    # Pulls from
+    # `SeregaEngine::Pulls.collect`, one per source of the parent group
+    attr_reader :pulls
+
+    # Each source is wrapped in the serializer's presenter, so value reading
+    # and batch loaders alike see presenters.
+    def initialize(run, plan, sources, pulls)
+      @run = run
+      @plan = plan
+      @context = run.context
+      presenter = plan.presenter
+      @sources = presenter ? sources.map { |source| presenter.new(source, @context) } : sources
+      @pulls = pulls
+      @child_groups = nil
+      @serialized = nil
+      @loaded_batches = nil
+      @attribute_values = nil
+    end
+
+    # Runs the preloads, and makes one child group per relation point, in the
+    # order of the relation points.
+    def discover
+      run_preloads
+
+      relation_points = plan.relation_points
+      return FROZEN_EMPTY_ARRAY if relation_points.empty?
+
+      @child_groups = relation_points.map { |point| child_group(point) }
+    end
+
+    # Builds the serialized objects.
+    def build
+      batches = plan.points.map { |point| batches_for(point) } if plan.batch_points?
+      @serialized = plan.result_builder(run.mode).call(@sources, @context, batches, relations)
+    end
+
+    private
+
+    # Relation values of each relation point, taken from its built child
+    # group, or nil without relation points
+    def relations
+      child_groups = @child_groups
+      return unless child_groups
+
+      relation_points = plan.relation_points
+      relations = {}
+      index = 0
+
+      while index < relation_points.size
+        child_group = child_groups[index]
+        relations[relation_points[index]] = SeregaEngine::Pulls.take!(child_group.serialized, child_group.pulls)
+        index += 1
+      end
+
+      relations
+    end
+
+    # Reads the relation sources of the point, and makes their child group
+    def child_group(point)
+      batches = batches_for(point)
+      child_sources = []
+      pulls =
+        if point.conditional?
+          relation_sources = read_conditional_relation_sources(point, batches)
+          SeregaEngine::Pulls.collect_conditional(child_sources, relation_sources, point.many, point.collection_classes)
+        else
+          relation_sources = read_relation_sources(point, batches)
+          SeregaEngine::Pulls.collect(child_sources, relation_sources, point.many, point.collection_classes)
+        end
+      run.new_source_group(point.child_plan, child_sources, pulls)
+    end
+
+    # Runs the preloads of all points with the serializer's preload handler.
+    # Preload handlers get the sources without presenters.
+    def run_preloads
+      points = plan.preload_points
+      return if points.empty?
+
+      serializer_class = plan.serializer_class
+      handler = serializer_class.preload_with
+      sources = plan.presenter ? @sources.map(&:__getobj__) : @sources
+
+      points.each do |point|
+        unless handler
+          raise SeregaError, "The :preload option requires a preload handler. Register one with `preload_with` (the :activerecord_preloads plugin does this for you)."
+        end
+
+        handler.call(sources, point.preloads)
+      rescue => error
+        SeregaUtils::SerializedAttributeError.call(error, point)
+      end
+    end
+
+    # Loads the batch loaders of the point, each once for all sources of
+    # the group. An attribute with an inline batch loader uses it, other
+    # attributes use the named batch loaders of the serializer. Returns nil
+    # when the point has no batch loaders.
+    def batches_for(point)
+      names = point.batch_loaders
+      return if names.empty?
+
+      inline_loader = point.attribute.inline_batch_loader
+      loaders = plan.serializer_class.batch_loaders
+      loaded_batches = (@loaded_batches ||= {}.compare_by_identity)
+      names.to_h do |name|
+        loader = inline_loader || loaders[name]
+        [name, loaded_batches[loader] ||= loader.load(@sources, @context)]
+      end
+    rescue => error
+      SeregaUtils::SerializedAttributeError.call(error, point)
+    end
+
+    # SeregaAttributeValues of the serializer: the methods that read
+    # attribute values with plain Ruby code
+    def attribute_values
+      @attribute_values ||= plan.serializer_class::SeregaAttributeValues.new
+    end
+
+    # Reads the relation source of every source: what the relation
+    # attribute returns, for example `user.posts`.
+    def read_relation_sources(point, batches)
+      attribute = point.attribute
+      value_method = attribute.value_method
+      context = @context
+
+      if value_method
+        values = attribute_values
+        @sources.map { |source| values.__send__(value_method, source) }
+      else
+        @sources.map { |source| attribute.value(source, context, batches: batches) }
+      end
+    rescue => error
+      SeregaUtils::SerializedAttributeError.call(error, point)
+    end
+
+    # Reads the relation source of every source of a conditional relation.
+    # A source failing the :if or :unless condition gets SKIP.
+    def read_conditional_relation_sources(point, batches)
+      attribute = point.attribute
+      value_method = attribute.value_method
+      values = attribute_values if value_method
+      conditions = attribute.conditions
+      context = @context
+
+      @sources.map do |source|
+        next SeregaEngine::SKIP unless conditions.satisfy?(source, context)
+
+        begin
+          value_method ? values.__send__(value_method, source) : attribute.value(source, context, batches: batches)
+        rescue => error
+          SeregaUtils::SerializedAttributeError.call(error, point)
+        end
+      end
+    end
+  end
+end

data/lib/serega/utils/collection_detector.rb

@@ -1,26 +1,32 @@
 # frozen_string_literal: true
 
 class Serega
-  # @private
-  module SeregaUtils
+  module SeregaUtils # :nodoc:
     #
     # Utility to check if an object should be serialized as a collection.
     #
     # Hashes and Structs are Enumerable, but enumerate their own member
     # values, so they are treated as single objects.
     #
-    # @private
-    class CollectionDetector
+    class CollectionDetector # :nodoc:
+      # Number of classes a Hash of known classes keeps
+      MAX_KNOWN_CLASSES = 8
+
       class << self
-        #
-        # Checks if provided object is a collection of objects
-        #
-        # @param object [Object] Serialized object
-        #
-        # @return [Boolean] whether object should be serialized as a collection
-        #
-        def call(object)
-          object.is_a?(Enumerable) && !object.is_a?(Hash) && !object.is_a?(Struct)
+        # Checks if provided object is a collection of objects. Remembers the
+        # answer for the class of the object in `known_classes`, up to
+        # MAX_KNOWN_CLASSES classes: `is_a?(Enumerable)` checks all
+        # ancestors of a class that does not include Enumerable.
+        def call(object, known_classes)
+          return true if object.instance_of?(Array)
+
+          object_class = object.class
+          collection = known_classes[object_class]
+          return collection unless collection.nil?
+
+          collection = object.is_a?(Enumerable) && !object.is_a?(Hash) && !object.is_a?(Struct)
+          known_classes[object_class] = collection if known_classes.size < MAX_KNOWN_CLASSES
+          collection
         end
       end
     end

data/lib/serega/utils/deep_merge.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaUtils # :nodoc:
+    #
+    # Merges nested hashes
+    #
+    class DeepMerge # :nodoc:
+      class << self
+        # Merges `other` into `hash` in place. Nested hashes merge into new
+        # hashes, thus `other` stays unchanged. Other values of `other` win.
+        def call(hash, other)
+          hash.merge!(other) { |_key, this_val, other_val| merge_values(this_val, other_val) }
+        end
+
+        private
+
+        def merge_values(this_val, other_val)
+          return other_val unless this_val.is_a?(Hash) && other_val.is_a?(Hash)
+
+          this_val.merge(other_val) { |_key, this_nested, other_nested| merge_values(this_nested, other_nested) }
+        end
+      end
+    end
+  end
+end

data/lib/serega/utils/enum_deep_dup.rb

@@ -4,23 +4,15 @@ class Serega
   #
   # Utilities
   #
-  # @private
-  module SeregaUtils
+  module SeregaUtils # :nodoc:
     #
-    # Duplicates nested hashes and arrays
-    # It does not duplicate any non-Array and non-Hash values
+    # Duplicates nested hashes, arrays and strings
+    # It does not duplicate any other values
     #
-    # @private
-    class EnumDeepDup
+    class EnumDeepDup # :nodoc:
       class << self
-        #
-        # Deeply duplicate provided Array or Hash data
-        # It does not duplicate any non-Array and non-Hash values
-        #
-        # @param data [Hash, Array] Data to duplicate
-        #
-        # @return [Hash, Array] Duplicated data
-        #
+        # Deeply duplicate provided Array, Hash or String data
+        # It does not duplicate any other values
         def call(data)
           case data
           when Hash
@@ -30,9 +22,11 @@ class Serega
           when Array
             data = data.dup
             dup_array_values(data)
+          when String
+            data.dup
+          else
+            data
           end
-
-          data
         end
 
         private

data/lib/serega/utils/enum_deep_freeze.rb

@@ -4,21 +4,13 @@ class Serega
   #
   # Utilities
   #
-  # @private
-  module SeregaUtils
+  module SeregaUtils # :nodoc:
     #
-    # Utility to freeze nested hashes and arrays
+    # Utility to freeze nested hashes, arrays and strings
     #
-    # @private
-    class EnumDeepFreeze
+    class EnumDeepFreeze # :nodoc:
       class << self
-        #
-        # Freezes nested hashes and arrays
-        #
-        # @param data[Hash, Array] data to freeze
-        #
-        # @return [Hash, Array] same deeply frozen data
-        #
+        # Freezes nested hashes and arrays, replaces strings with frozen copies
         def call(data)
           case data
           when Hash
@@ -27,9 +19,11 @@ class Serega
           when Array
             data.map! { |value| call(value) }
             data.freeze
+          when String
+            -data
+          else
+            data
           end
-
-          data
         end
       end
     end

data/lib/serega/utils/method_signature.rb

@@ -4,31 +4,22 @@ class Serega
   #
   # Utilities
   #
-  # @private
-  module SeregaUtils
+  module SeregaUtils # :nodoc:
     #
     # Utility to make method arguments signature
     #
-    # @private
-    class MethodSignature
+    class MethodSignature # :nodoc:
       SYMBOL_TO_PROC_SIGNATURE_RUBY2 = [[:rest]]
       SYMBOL_TO_PROC_SIGNATURE_RUBY3 = [[:req], [:rest]]
       private_constant :SYMBOL_TO_PROC_SIGNATURE_RUBY2
       private_constant :SYMBOL_TO_PROC_SIGNATURE_RUBY3
 
       class << self
-        #
-        # Generates method arguments signature
-        #
-        # @param callable [#call] callable object
-        # @param pos_limit [Integer] Max count of positional parameters
-        # @param keyword_args [Array<Symbol>] List of accepted keyword argument names
-        #
-        # @return [String] Method signature which consist of number of positional parameters and
-        #    keyword parameter names joined with undescrore.
-        #
+        # Generates method arguments signature: the count of positional
+        # parameters and the keyword parameter names, joined with underscores,
+        # like "1_ctx"
         def call(callable, pos_limit:, keyword_args: [])
-          params = callable.is_a?(Proc) ? callable.parameters : callable.method(:call).parameters
+          params = (callable.is_a?(Proc) || callable.is_a?(Method)) ? callable.parameters : callable.method(:call).parameters
 
           # Procs (but not lambdas) can accept all provided parameters
           return full_signature(pos_limit, keyword_args) if params.empty? && callable.is_a?(Proc) && !callable.lambda?

data/lib/serega/utils/parse_string_modifiers.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaUtils # :nodoc:
+    #
+    # Parses fields listed in one String, with nested fields in parentheses
+    #
+    class ParseStringModifiers # :nodoc:
+      SEPARATOR = /[,()]/
+      COMMA = ",".ord
+      LPAREN = "(".ord
+      private_constant :SEPARATOR, :COMMA, :LPAREN
+
+      class << self
+        # Parses string modifiers
+        #
+        #   parse("user") => { user: {} }
+        #   parse("user(id)") => { user: { id: {} } }
+        #   parse("user(id,name)") => { user: { id: {}, name: {} } }
+        #   parse("user,comments") => { user: {}, comments: {} }
+        #   parse("user(comments(text))") => { user: { comments: { text: {} } } }
+        def parse(fields)
+          result = {}
+          storage = result
+          parent_storages = nil
+          start = 0
+
+          while (index = fields.byteindex(SEPARATOR, start))
+            name = extract_name(fields, start, index)
+            separator = fields.getbyte(index)
+
+            if separator == COMMA
+              storage[name] = FROZEN_EMPTY_HASH if name
+            elsif separator == LPAREN
+              if name
+                (parent_storages ||= []) << storage
+                storage = storage[name] = {}
+              end
+            else
+              storage[name] = FROZEN_EMPTY_HASH if name
+              storage = parent_storages&.pop || result
+            end
+
+            start = index + 1
+          end
+
+          name = extract_name(fields, start, fields.bytesize)
+          storage[name] = FROZEN_EMPTY_HASH if name
+
+          result
+        end
+
+        private
+
+        def extract_name(fields, start, finish)
+          name = fields.byteslice(start, finish - start)
+          name.strip!
+          name.empty? ? nil : name.to_sym
+        end
+      end
+    end
+  end
+end

data/lib/serega/utils/ractor_local.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+class Serega
+  #
+  # Utilities
+  #
+  module SeregaUtils # :nodoc:
+    #
+    # Values stored in the current Ractor by key
+    #
+    class RactorLocal # :nodoc:
+      class << self
+        # Returns the key of the owner value with the name
+        def key(owner, name)
+          :"serega_#{name}_#{owner.object_id}"
+        end
+
+        # :nocov:
+        if defined?(Ractor.[])
+          # Returns the value of the key in the current Ractor, stores the
+          # block result when there is none
+          def fetch(key)
+            Ractor[key] ||= yield
+          end
+        else
+          # Returns the value of the key in the current Ractor, stores the
+          # block result when there is none
+          def fetch(key)
+            Ractor.current[key] ||= yield
+          end
+        end
+        # :nocov:
+      end
+    end
+  end
+end

data/lib/serega/utils/serialized_attribute_error.rb

@@ -1,29 +1,69 @@
 # frozen_string_literal: true
 
 class Serega
-  # @private
-  module SeregaUtils
+  module SeregaUtils # :nodoc:
     #
     # Reraises an error, adding which attribute and serializer were being
-    # serialized when it happened. Shared by the synchronous serialization walk
-    # and the batch attach phase so the message stays identical for every
-    # attribute, whether its value is resolved inline or during batch loading.
+    # serialized when it happened, and where the attribute is defined. Value
+    # reads, preloads, batch loaders and attribute conditions use it.
     #
-    # @private
-    module SerializedAttributeError
-      module_function
-
-      #
-      # @param error [Exception] Original error
-      # @param point [SeregaPlanPoint] Plan point being serialized
-      #
-      # @return [void]
-      #
-      def call(error, point)
-        raise error.exception(<<~MESSAGE.strip)
-          #{error.message}
-          (when serializing '#{point.name}' attribute in #{point.class.serializer_class})
-        MESSAGE
+    module SerializedAttributeError # :nodoc:
+      # File name of the generated code in backtraces
+      GENERATED_CODE_FILE = "(serega generated code)"
+
+      class << self
+        # Reraises an error raised while a value is read, preloaded or batch
+        # loaded. An error raised in the generated code gets a backtrace line at
+        # the attribute, above the line of the generated code:
+        #
+        #   app/serializers/user_serializer.rb:3:in 'attribute :full_name of UserSerializer'
+        #   (serega generated code):20:in 'call'
+        def call(error, point)
+          location = point.attribute.location
+          serializer_class = point.plan.serializer_class
+          defined_at = location ? ", #{location}" : ""
+
+          exception = error.exception(<<~MESSAGE.strip)
+            #{error.message}
+            (when serializing the '#{point.name}' attribute in #{serializer_class}#{defined_at})
+          MESSAGE
+          add_attribute_line(exception, "#{location}:in 'attribute :#{point.name} of #{serializer_class}'") if location
+          raise exception
+        end
+
+        # Reraises an error raised by an :if, :unless, :if_value or
+        # :unless_value condition
+        def condition(error, attribute, condition_name)
+          location = attribute.location
+          defined_at = location ? ", #{location}" : ""
+
+          raise error.exception(<<~MESSAGE.strip)
+            #{error.message}
+            (when checking the :#{condition_name} condition of the '#{attribute.name}' attribute in #{attribute.serializer_class}#{defined_at})
+          MESSAGE
+        end
+
+        private
+
+        # Puts the line above the line of the generated code that called this
+        # module. The backtrace and the call stack share the outer lines, up
+        # to that line: the backtrace has the line of the read there, the
+        # call stack the line of the rescue.
+        def add_attribute_line(exception, line)
+          backtrace = exception.backtrace
+          return unless backtrace
+
+          index = backtrace.size - shared_outer_lines_count(backtrace, caller(2)) - 1
+          return if index.negative? || !backtrace[index].start_with?(GENERATED_CODE_FILE)
+
+          exception.set_backtrace(backtrace.dup.insert(index, line))
+        end
+
+        def shared_outer_lines_count(backtrace, stack)
+          count = 0
+          count += 1 while count < backtrace.size && count < stack.size && backtrace[-1 - count] == stack[-1 - count]
+          count
+        end
       end
     end
   end

data/lib/serega/utils/to_hash.rb

@@ -1,20 +1,14 @@
 # frozen_string_literal: true
 
 class Serega
-  # @private
-  module SeregaUtils
+  module SeregaUtils # :nodoc:
     #
     # Utility to transform almost anything to Hash
     #
-    # @private
-    class ToHash
+    class ToHash # :nodoc:
       class << self
-        #
         # Constructs deep hashes from provided data
         #
-        # @param value [Array, Hash, String, Symbol, NilClass, FalseClass, TrueClass] Value to transform
-        #
-        # @example
         #   Serega::SeregaUtils::ToHash.(nil) # => {}
         #   Serega::SeregaUtils::ToHash.(true) # => {}
         #   Serega::SeregaUtils::ToHash.(false) # => {}
@@ -24,16 +18,13 @@ class Serega
         #   Serega::SeregaUtils::ToHash.({ foo: nil, bar: true }) # => {:foo=>{}, :bar=>{}}
         #   Serega::SeregaUtils::ToHash.({ foo: :bar }) # => {:foo=>{:bar=>{}}}
         #   Serega::SeregaUtils::ToHash.({ foo: [:bar] }) # => {:foo=>{:bar=>{}}}
-        #
-        # @return [Hash] Transformed data
-        #
         def call(value)
           case value
           when Array then array_to_hash(value)
           when Hash then hash_to_hash(value)
-          when NilClass, FalseClass, TrueClass then nil_to_hash(value)
-          when String then string_to_hash(value)
-          when Symbol then symbol_to_hash(value)
+          when NilClass, FalseClass, TrueClass then FROZEN_EMPTY_HASH
+          when String then {value.to_sym => FROZEN_EMPTY_HASH}
+          when Symbol then {value => FROZEN_EMPTY_HASH}
           else raise SeregaError, "Can't convert #{value.class} class object to hash"
           end
         end
@@ -63,18 +54,6 @@ class Serega
           end
           res
         end
-
-        def nil_to_hash(_value)
-          FROZEN_EMPTY_HASH
-        end
-
-        def string_to_hash(value)
-          {value.to_sym => FROZEN_EMPTY_HASH}
-        end
-
-        def symbol_to_hash(value)
-          {value => FROZEN_EMPTY_HASH}
-        end
       end
     end
   end

data/lib/serega/validations/attribute/check_block.rb

@@ -1,18 +1,15 @@
 # frozen_string_literal: true
 
 class Serega
-  # @private
-  module SeregaValidations
+  module SeregaValidations # :nodoc:
     #
     # Attribute parameters validators
     #
-    # @private
-    module Attribute
+    module Attribute # :nodoc:
       #
       # Attribute `block` parameter validator
       #
-      # @private
-      class CheckBlock
+      class CheckBlock # :nodoc:
         # Explains the changed attribute block behavior. Shown when the block
         # looks like an old-style value block — it accepts parameters or
         # defines no attributes.
@@ -23,25 +20,16 @@ class Serega
           " use the `value: <callable>` option instead."
 
         class << self
-          #
           # Checks block parameter provided with attribute.
           #
           # The block defines attributes of a nested anonymous serializer, so
           # it is executed in the context of that serializer and must accept
           # no parameters.
           #
-          # @example
           #   attribute :statistics, method: :itself do
           #     attribute :likes_count
           #     attribute :comments_count
           #   end
-          #
-          # @param block [Proc] Block that defines nested serializer attributes
-          #
-          # @raise [SeregaError] SeregaError that block has invalid arguments
-          #
-          # @return [void]
-          #
           def call(block)
             return unless block