serega 0.41.0 → 0.50.0

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
 

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

@@ -1,31 +1,20 @@
 # frozen_string_literal: true
 
 class Serega
-  # @private
-  module SeregaValidations
-    # @private
-    module Attribute
+  module SeregaValidations # :nodoc:
+    module Attribute # :nodoc:
       #
       # Attribute `name` parameter validator
       #
-      # @private
-      class CheckName
+      class CheckName # :nodoc:
         # Regexp for valid attribute name
         FORMAT = /\A[\w~-]+\z/
 
         class << self
-          #
           # Checks allowed characters.
           # Allowed characters: "a-z", "A-Z", "0-9", "_", "-", "~".
-          #
-          # @param name [String, Symbol] Attribute name
-          #
-          # @raise [SeregaError] when name has invalid format
-          # @return [void]
-          #
           def call(name)
-            name = SeregaUtils::SymbolName.call(name)
-            raise SeregaError, message(name) unless FORMAT.match?(name)
+            raise SeregaError, message(name.to_s) unless FORMAT.match?(name)
           end
 
           private

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

@@ -1,28 +1,16 @@
 # frozen_string_literal: true
 
 class Serega
-  # @private
-  module SeregaValidations
-    # @private
-    module Attribute
+  module SeregaValidations # :nodoc:
+    module Attribute # :nodoc:
       #
       # Attribute `:base_serializer` option validator
       #
-      # @private
-      class CheckOptBaseSerializer
+      class CheckOptBaseSerializer # :nodoc:
         class << self
-          #
           # Checks attribute :base_serializer option. It specifies the parent
           # class for the nested serializer defined with the attribute block,
           # so it makes sense only when a block is provided.
-          #
-          # @param opts [Hash] Attribute options
-          # @param block [nil, Proc] Attribute block (defines a nested serializer)
-          #
-          # @raise [SeregaError] SeregaError that option has invalid value
-          #
-          # @return [void]
-          #
           def call(opts, block = nil)
             return unless opts.key?(:base_serializer)