serega 0.42.0 → 0.50.0

data/lib/serega/errors.rb

@@ -1,23 +1,51 @@
 # frozen_string_literal: true
 
 class Serega
+  # Raised on invalid definitions and options, and on changes of a locked
+  # serializer. Parent class of the other Serega errors.
   #
-  # Base exception class
-  #
+  # See [Errors](https://github.com/andreyruby/serega/blob/master/docs/errors.md).
   class SeregaError < StandardError; end
 
-  # Raised when serializer is initiated using not existing attribute
+  # Raised when `only:`, `except:` or `with:` names an unknown field
+  #
+  # ```ruby
+  # UserSerializer.to_h(user, only: [:nickname, {friends: :age}])
+  # # => Serega::AttributeNotExist: Not existing attributes: nickname, friends(age)
+  # ```
   #
-  # @example
-  #   Serega.new(only: 'FOO')
-  #   # => Attribute 'FOO' not exists (Serega::AttributeNotExist)
+  # See [Unknown fields](https://github.com/andreyruby/serega/blob/master/docs/selecting-fields.md#unknown-fields).
   class AttributeNotExist < SeregaError
-    attr_reader :serializer, :attributes
+    # Serializer that has no such fields
+    attr_reader :serializer
+
+    # Unknown fields, for example `["nickname", "friends(age)"]`
+    attr_reader :attributes
 
-    def initialize(message = nil, serializer = nil, attributes = nil)
+    def initialize(message = nil, serializer = nil, attributes = nil) # :nodoc:
       super(message)
       @serializer = serializer
       @attributes = attributes
     end
   end
+
+  # Raised when fields nest deeper than `config.depth_limit` of the
+  # serializer that starts the serialization
+  #
+  # ```ruby
+  # UserSerializer.to_h(user, with: {friends: :friends})
+  # # => Serega::DepthLimitError: Depth limit was exceeded
+  # ```
+  #
+  # See [Depth limit](https://github.com/andreyruby/serega/blob/master/docs/configuration.md#depth-limit).
+  class DepthLimitError < SeregaError
+    # Path that exceeds the limit, for example
+    # `UserSerializer (depth limit: 2) -> friends -> friends`
+    attr_reader :details
+
+    def initialize(message = nil, details = nil) # :nodoc:
+      super(message)
+      @details = details
+    end
+  end
 end

data/lib/serega/formatter.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+class Serega
+  #
+  # Formats attribute values. A formatter is one of:
+  # - a callable that gets the value, and the context when it has a second
+  #   parameter or the :ctx keyword;
+  # - a method name, called on the value;
+  # - an Array of a method name and its arguments, for example `[:round, 2]`;
+  # - a Hash with one of them as `:use` and the `:allow_nil` option.
+  #
+  # With `allow_nil: true` a nil value stays nil and is not formatted.
+  #
+  class SeregaFormatter # :nodoc:
+    # Callable that formats a value, nil for a method formatter
+    attr_reader :callable
+
+    # Arguments of the method, nil for a callable formatter
+    attr_reader :args
+
+    def initialize(formatter)
+      formatter = {use: formatter} unless formatter.is_a?(Hash)
+      use = formatter[:use]
+      @allow_nil = formatter.fetch(:allow_nil, false)
+
+      if use.respond_to?(:call)
+        @method_name = nil
+        @args = nil
+        @callable = use
+        @signature = SeregaUtils::MethodSignature.call(use, pos_limit: 2, keyword_args: [:ctx])
+      else
+        method_name, *args = use
+        @method_name = method_name
+        @args = args
+        @callable = nil
+        @signature = nil
+      end
+    end
+
+    # Formats the value
+    def call(value, context)
+      return if value.nil? && @allow_nil
+      return value.public_send(@method_name, *@args) if @method_name
+
+      case @signature
+      when "1" then @callable.call(value)
+      when "1_ctx" then @callable.call(value, ctx: context)
+      else @callable.call(value, context) # "2"
+      end
+    end
+
+    # Ruby code that formats the value of `value_code`. A method is called
+    # directly, for example `(source.created_at).iso8601(3)`. Literal
+    # arguments are written in the code, other arguments are read from the
+    # Array that `args_code` reads. A callable is read with `callable_code`.
+    def code(value_code, callable_code, args_code)
+      return method_call_code(value_code, args_code) if @method_name
+      return unless @signature == "1"
+      return "#{callable_code}.call(#{value_code})" unless @allow_nil
+
+      "(value = #{value_code}).nil? ? nil : #{callable_code}.call(value)"
+    end
+
+    private
+
+    def method_call_code(value_code, args_code)
+      operator = @allow_nil ? "&." : "."
+      arguments = @args.each_with_index.map { |arg, index| argument_code(arg, index, args_code) }
+
+      unless SeregaResultCode::PLAIN_METHOD_NAME.match?(@method_name)
+        send_arguments = [@method_name.inspect, *arguments]
+        return "(#{value_code})#{operator}public_send(#{send_arguments.join(", ")})"
+      end
+
+      return "(#{value_code})#{operator}#{@method_name}" if arguments.empty?
+
+      "(#{value_code})#{operator}#{@method_name}(#{arguments.join(", ")})"
+    end
+
+    # Literal arguments are written in the code, other arguments are read
+    # from the Array of arguments
+    def argument_code(arg, index, args_code)
+      literal?(arg) ? literal_code(arg) : "#{args_code}[#{index}]"
+    end
+
+    def literal?(arg)
+      case arg
+      when Integer, Symbol, String, true, false, nil then true
+      when Float then arg.finite?
+      else false
+      end
+    end
+
+    def literal_code(arg)
+      arg.is_a?(String) ? "#{arg.inspect}.freeze" : arg.inspect
+    end
+  end
+end

data/lib/serega/plan/cache.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+class Serega
+  class SeregaPlan # :nodoc:
+    #
+    # Serialization plans of one serializer, cached by modifiers.
+    # Validates initiate options before building a plan.
+    #
+    class Cache # :nodoc:
+      # Cached plan, whether its modifiers were validated, and the modifiers
+      # as provided
+      CachedPlan = Struct.new(:plan, :validated, :only, :with, :except)
+      private_constant :CachedPlan
+
+      # Initializes empty plans cache of the serializer
+      def initialize(serializer_class)
+        @serializer_class = serializer_class
+        @default_plan = nil
+        @plans = {}
+      end
+
+      # Returns serialization plan for provided modifiers.
+      # The plan without modifiers is always cached; plans with modifiers are
+      # cached by modifiers as provided when `max_cached_plans_per_serializer_count`
+      # is positive. Modifiers are parsed and validated when a plan is built.
+      def fetch(only, with, except, check_initiate_params: false)
+        return default_plan if only.nil? && with.nil? && except.nil?
+
+        max_size = @serializer_class.config.max_cached_plans_per_serializer_count
+        return build(only, with, except, check_initiate_params) if max_size.zero?
+
+        cached_plan(only, with, except, max_size, check_initiate_params)
+      end
+
+      private
+
+      def default_plan
+        @default_plan ||= SeregaPlan.new(@serializer_class, nil, FROZEN_EMPTY_HASH)
+      end
+
+      # Keeps plans by the hash of the hash values of the modifiers, and
+      # compares each modifier with the cached one: an Array of the modifiers
+      # as the key hashes and compares nested arrays inside a recursion guard.
+      # Modifiers with the hash of other cached modifiers replace them.
+      def cached_plan(only, with, except, max_size, check_initiate_params)
+        key = [only.hash, with.hash, except.hash].hash # rubocop:disable Security/CompoundHash -- `[only, with, except].hash` hashes nested arrays inside a recursion guard
+        cached = @plans[key]
+        return reuse(cached, only, with, except, check_initiate_params) if cached && same_modifiers?(cached, only, with, except)
+
+        plan = build(only, with, except, check_initiate_params)
+        @plans[key] = CachedPlan.new(plan, check_initiate_params, *frozen_copy([only, with, except]))
+        @plans.shift if @plans.length > max_size
+        plan
+      end
+
+      def same_modifiers?(cached, only, with, except)
+        only.eql?(cached.only) && with.eql?(cached.with) && except.eql?(cached.except)
+      end
+
+      def reuse(cached, only, with, except, check_initiate_params)
+        if check_initiate_params && !cached.validated
+          validate(parse_modifiers(only, with, except))
+          cached.validated = true
+        end
+
+        cached.plan
+      end
+
+      def build(only, with, except, check_initiate_params)
+        modifiers = parse_modifiers(only, with, except)
+        return default_plan if modifiers[:only].empty? && modifiers[:with].empty? && modifiers[:except].empty?
+
+        validate(modifiers) if check_initiate_params
+        SeregaPlan.new(@serializer_class, nil, modifiers)
+      end
+
+      def parse_modifiers(only, with, except)
+        {only: parse_modifier(only), with: parse_modifier(with), except: parse_modifier(except)}
+      end
+
+      def parse_modifier(value)
+        return SeregaUtils::ParseStringModifiers.parse(value) if value.is_a?(String)
+
+        SeregaUtils::ToHash.call(value)
+      end
+
+      def frozen_copy(modifiers)
+        SeregaUtils::EnumDeepFreeze.call(SeregaUtils::EnumDeepDup.call(modifiers))
+      end
+
+      def validate(modifiers)
+        SeregaValidations::Initiate::CheckModifiers.new.call(@serializer_class, modifiers[:only], modifiers[:with], modifiers[:except])
+      end
+    end
+  end
+end

data/lib/serega/plan/per_ractor_cache.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+class Serega
+  class SeregaPlan # :nodoc:
+    #
+    # Shareable plans cache of a shareable serializer, keeps the plans of each
+    # Ractor apart
+    #
+    class PerRactorCache # :nodoc:
+      def initialize(serializer_class)
+        @serializer_class = serializer_class
+        @key = SeregaUtils::RactorLocal.key(serializer_class, :plan_cache)
+        freeze
+      end
+
+      # Returns serialization plan from the plans cache of the current Ractor
+      def fetch(only, with, except, check_initiate_params: false)
+        plan_cache = SeregaUtils::RactorLocal.fetch(@key) { SeregaPlan::Cache.new(@serializer_class) }
+        plan_cache.fetch(only, with, except, check_initiate_params: check_initiate_params)
+      end
+    end
+  end
+end

data/lib/serega/plan.rb

@@ -5,152 +5,125 @@ class Serega
   # Constructs plan - list of serialized attributes.
   # We will traverse this plan to construct serialized response.
   #
-  # @private
-  class SeregaPlan
-    #
-    # SeregaPlan class methods
-    #
-    # @private
-    module ClassMethods
-      #
-      # Constructs plan of attributes that should be serialized.
-      #
-      # @param opts Serialization parameters
-      # @option opts [Hash] :only The only attributes to serialize
-      # @option opts [Hash] :except Attributes to hide
-      # @option opts [Hash] :with Attributes (usually marked `hide: true`) to serialize additionally
-      #
-      # @return [SeregaPlan] Serialization plan
-      #
-      def call(opts)
-        max_cache_size = serializer_class.config.max_cached_plans_per_serializer_count
-        return new(nil, opts) if max_cache_size.zero?
-
-        cached_plan_for(opts, max_cache_size)
-      end
-
-      #
-      # Returns (and caches) the Data class for the given set of field names.
-      # Uses the Array as cache key so the same Data class is reused across
-      # all plan instances with identical fields.
-      #
-      # @param point_names [Array<Symbol>] Attribute names for the Data members
-      # @return [Class] Subclass of Data
-      #
-      def data_class_for(point_names)
-        (@data_classes ||= {})[point_names] ||= Data.define(*point_names)
-      end
-
-      private
-
-      def cached_plan_for(opts, max_cache_size)
-        @cache ||= {}
-        cache_key = construct_cache_key(opts)
-
-        plan = @cache[cache_key] ||= new(nil, opts)
-        @cache.shift if @cache.length > max_cache_size
-        plan
-      end
+  class SeregaPlan # :nodoc:
+    # Serializer of the plan
+    attr_reader :serializer_class
+
+    # Parent plan point
+    attr_reader :parent_plan_point
+
+    # Serialization points
+    attr_reader :points
+
+    # Serialization points with child plans
+    attr_reader :relation_points
+
+    # Whether the root objects of a class are collections
+    attr_reader :collection_classes
+
+    # Presenter class that wraps the sources in the Ractor of the plan, `nil`
+    # without presenter methods
+    attr_reader :presenter
+
+    # Instantiate new serialization plan. Raises DepthLimitError when the plan
+    # nests deeper than the depth limit of the root serializer.
+    def initialize(serializer_class, parent_plan_point, modifiers)
+      check_depth_limit(parent_plan_point) if parent_plan_point
+      serializer_class.lock
+      @serializer_class = serializer_class
+      @parent_plan_point = parent_plan_point
+      @presenter = serializer_class.local_presenter
+      @points = attributes_points(modifiers)
+      @relation_points = points.select(&:child_plan).freeze
+      @preload_points = points.select(&:preloads).freeze
+      @batch_points = points.any? { |point| !point.batch_loaders.empty? }
+      @flat = relation_points.empty? && preload_points.empty? && !@batch_points && !@presenter
+      @result_builders = {}
+      @collection_classes = {}.compare_by_identity
+      direct = parent_plan_point.nil? && @flat && !serializer_class.prepare_initial_objects_signature
+      @direct_hash_builder = direct ? result_builder(:hash) : nil
+    # :nocov:
+    rescue *RACTOR_ISOLATION_ERRORS
+      raise if serializer_class.shareable?
+
+      raise SeregaError, "#{serializer_class} can not serialize in other Ractors. Call `make_shareable!` at the end of its definition"
+      # :nocov:
+    end
 
-      def construct_cache_key(opts, cache_key = nil)
-        return nil if opts.empty?
+    # Serialization points with preloads
+    attr_reader :preload_points
 
-        cache_key ||= +""
+    # Hash result builder of a flat root plan whose serializer prepares no
+    # initial objects. `Serega#call` builds one source with it directly.
+    attr_reader :direct_hash_builder
 
-        opts.each do |key, nested_opts|
-          cache_key.insert(-1, SeregaUtils::SymbolName.call(key))
-          cache_key.insert(-1, "-")
-          construct_cache_key(nested_opts, cache_key)
-        end
+    # Whether any point uses batch loaders
+    def batch_points?
+      @batch_points
+    end
 
-        cache_key
-      end
+    # A flat plan has no relations, preloads, batch loaders and presenter.
+    # Its sources need no source groups.
+    def flat?
+      @flat
     end
 
-    #
-    # SeregaPlan instance methods
-    #
-    # @private
-    module InstanceMethods
-      # Parent plan point
-      # @return [SeregaPlanPoint, nil]
-      attr_reader :parent_plan_point
-
-      # Serialization points
-      # @return [Array<SeregaPlanPoint>] points to serialize
-      attr_reader :points
-
-      # Named serialization points
-      # @return [Hash] Named points
-      attr_reader :points_hash
-
-      #
-      # Instantiate new serialization plan
-      #
-      # Patched by
-      #  - depth_limit plugin, which checks depth limit is not exceeded when adding new plan
-      #
-      # @param parent_plan_point [SeregaPlanPoint, nil] Parent plan_point
-      # @param modifiers [Hash] Serialization parameters
-      # @option modifiers [Hash] :only The only attributes to serialize
-      # @option modifiers [Hash] :except Attributes to hide
-      # @option modifiers [Hash] :with Hidden attributes to serialize additionally
-      #
-      # @return [SeregaPlan] Serialization plan
-      #
-      def initialize(parent_plan_point, modifiers)
-        @parent_plan_point = parent_plan_point
-        @points = attributes_points(modifiers)
-        @points_hash = points.to_h { |point| [point.name, point] }
-      end
+    # Result builder of this plan in the serialization mode
+    def result_builder(mode)
+      @result_builders[mode] ||= SeregaResultBuilder.new(serializer_class, mode, points)
+    end
 
-      #
-      # Serializer class of current plan
-      #
-      def serializer_class
-        self.class.serializer_class
-      end
+    private
 
-      # Returns the Data class whose members match this plan's serialized fields.
-      # Delegates to the class-level cache so identical field sets share one Data class.
-      #
-      # @return [Class] Subclass of Data
-      #
-      def data_class
-        @data_class ||= self.class.data_class_for(point_names)
+    def check_depth_limit(parent_plan_point)
+      depth = 2
+      root_plan = parent_plan_point.plan
+      while (point = root_plan.parent_plan_point)
+        depth += 1
+        root_plan = point.plan
       end
 
-      private
+      root_serializer = root_plan.serializer_class
+      limit = root_serializer.config.depth_limit
+      return if limit.nil? || depth <= limit
 
-      def attributes_points(modifiers)
-        only = modifiers[:only] || FROZEN_EMPTY_HASH
-        except = modifiers[:except] || FROZEN_EMPTY_HASH
-        with = modifiers[:with] || FROZEN_EMPTY_HASH
-        points = []
+      names = [parent_plan_point.name]
+      point = parent_plan_point
+      names.unshift(point.name) while (point = point.plan.parent_plan_point)
+      raise DepthLimitError.new("Depth limit was exceeded", "#{root_serializer} (depth limit: #{limit}) -> #{names.join(" -> ")}")
+    end
 
-        serializer_class.attributes.each_value do |attribute|
-          next unless attribute.visible?(only: only, except: except, with: with)
+    def attributes_points(modifiers)
+      only = modifiers[:only] || FROZEN_EMPTY_HASH
+      except = modifiers[:except] || FROZEN_EMPTY_HASH
+      with = modifiers[:with] || FROZEN_EMPTY_HASH
+      only_limits = only_limits?(only, except, with)
+      points = []
 
-          child_fields =
-            if attribute.relation?
-              name = attribute.name
-              {only: only[name], with: with[name], except: except[name]}
-            end
+      serializer_class.attributes.each_value do |attribute|
+        next unless attribute.visible?(only, except, with, only_limits)
 
-          point = serializer_class::SeregaPlanPoint.new(self, attribute, child_fields)
-          points << point.freeze
-        end
+        child_fields =
+          if attribute.relation?
+            name = attribute.name
+            {only: only[name], with: with[name], except: except[name]}
+          end
 
-        points.freeze
+        point = SeregaPlanPoint.new(self, attribute, child_fields)
+        points << point.freeze
       end
 
-      def point_names
-        @point_names ||= points.map(&:name)
-      end
+      points.freeze
     end
 
-    extend ClassMethods
-    include InstanceMethods
-    extend SeregaHelpers::SerializerClassHelper
+    # `only` hides the fields it does not name when it names a field of
+    # this level without nested fields, or when `except` hides no field and
+    # `with` adds no field of this level
+    def only_limits?(only, except, with)
+      return false if only.empty?
+      return true if only.each_value.any?(&:empty?)
+
+      with.empty? && except.each_value.none?(&:empty?)
+    end
   end
 end