serega 0.41.0 → 0.50.0

data/lib/serega/plugins.rb

@@ -1,58 +1,25 @@
 # frozen_string_literal: true
 
 class Serega
-  # Plugins are stored here
+  # Built-in features, turned on with Serega::ClassMethods#plugin.
+  #
+  # See [Guides](https://github.com/andreyruby/serega/blob/master/docs/README.md).
   module SeregaPlugins
-    @plugins = {}
+    # Plugin module names, by plugin name
+    MODULES = { # :nodoc:
+      root: :Root,
+      metadata: :Metadata,
+      context_metadata: :ContextMetadata,
+      activerecord_preloads: :ActiverecordPreloads
+    }.freeze
 
     class << self
-      #
-      # Registers given plugin to be able to load it using symbol name.
-      #
-      # @param name [Symbol] Plugin name
-      # @param mod [Module] Plugin module
-      #
-      # @example Register plugin
-      #   SeregaPlugins.register_plugin(:plugin_name, PluginModule)
-      #
-      # @return [void]
-      #
-      # @private
-      def register_plugin(name, mod)
-        @plugins[name] = mod
-      end
-
-      #
-      # Loads plugin code and returns plugin core module.
-      #
-      # @param name [Symbol, Module] plugin name or plugin itself
-      #
-      # @raise [SeregaError] Raises SeregaError when plugin was not found
-      #
-      # @example Find plugin when providing name
-      #   SeregaPlugins.find_plugin(:presenter) # => SeregaPlugins::Presenter
-      #
-      # @example Find plugin when providing plugin itself
-      #   SeregaPlugins.find_plugin(Presenter) # => Presenter
-      #
-      # @return [Class<Module>] Plugin core module
-      #
-      # @private
-      def find_plugin(name)
-        return name if name.is_a?(Module)
-        return @plugins[name] if @plugins.key?(name)
-
-        require_plugin(name)
-
-        @plugins[name] || raise(SeregaError, "Plugin '#{name}' did not register itself correctly")
-      end
-
-      private
-
-      def require_plugin(name)
-        require "serega/plugins/#{name}/#{name}"
-      rescue LoadError
-        raise SeregaError, "Plugin '#{name}' does not exist"
+      # Loads the code of the plugin and returns its module. Raises
+      # SeregaError when the plugin does not exist.
+      def find(name) # :nodoc:
+        module_name = MODULES.fetch(name) { raise SeregaError, "Plugin #{name.inspect} does not exist" }
+        require_relative "plugins/#{name}/#{name}"
+        const_get(module_name)
       end
     end
   end

data/lib/serega/presenter.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+class Serega
+  # Wraps the object to serialize, so computed attribute values can be defined as
+  # methods instead of `:value` callables.
+  #
+  # SeregaPresenter inherits from SimpleDelegator:
+  # - All methods of the wrapped object are available directly inside presenter methods.
+  # - Methods not defined on SeregaPresenter are resolved via method_missing on the first call
+  #   and then defined as real delegators, so subsequent calls skip method_missing entirely.
+  # - The original object is accessible via __getobj__ (standard SimpleDelegator API).
+  # - The serialization context is accessible via the private method __ctx__.
+  #
+  # The `presenter do ... end` block is evaluated inside the serializer's own
+  # SeregaPresenter class, so multiple blocks accumulate.
+  #
+  #   class UserSerializer < Serega
+  #     attribute :name
+  #     attribute :role
+  #
+  #     presenter do
+  #       def name
+  #         [first_name, last_name].compact.join(' ') # first_name/last_name delegated to object
+  #       end
+  #
+  #       def role
+  #         id == __ctx__[:current_user_id] ? :self : :other
+  #       end
+  #     end
+  #   end
+  class SeregaPresenter < SimpleDelegator # :nodoc:
+    # Method names of delegators defined with a compiled `def`
+    PLAIN_METHOD_NAME = /\A[a-z_][a-zA-Z0-9_]*[?!]?\z/
+    private_constant :PLAIN_METHOD_NAME
+
+    #
+    # Delegator to the method of the wrapped object with the name it is
+    # called by. Delegators with other names are its aliases.
+    #
+    module CalleeDelegator # :nodoc:
+      #
+      # Calls the method of the wrapped object with the name of the alias
+      #
+      def __serega_delegate__(...)
+        __getobj__.public_send(__callee__, ...)
+      end
+    end
+
+    # Includes into each presenter class its own `Delegators` module.
+    # Delegators to the methods of the wrapped object are defined there after the
+    # first #method_missing hit. Presenter methods override them and can call
+    # them via `super`.
+    def self.inherited(subclass)
+      super
+      delegators = Module.new
+      delegators.include(CalleeDelegator)
+      subclass.const_set(:Delegators, delegators)
+      subclass.include(delegators)
+    end
+
+    # Defines a method that delegates to the wrapped object in the
+    # presenter class `Delegators` module
+    def self.define_delegator(name)
+      delegators = self::Delegators
+
+      if PLAIN_METHOD_NAME.match?(name)
+        delegators.module_eval(<<~RUBY, __FILE__, __LINE__ + 1)
+          def #{name}(...)
+            __getobj__.#{name}(...)
+          end
+        RUBY
+      else
+        delegators.alias_method(name, :__serega_delegate__)
+      end
+    end
+
+    # Defines delegators for the method names that the presenter class does
+    # not define itself, thus presenter methods stay in front of them
+    def self.define_delegators(names)
+      names.each do |name|
+        define_delegator(name) unless method_defined?(name) || private_method_defined?(name)
+      end
+    end
+
+    def initialize(object, ctx = nil)
+      super(object)
+      @__ctx__ = ctx
+    end
+
+    private
+
+    attr_reader :__ctx__
+
+    #
+    # Delegates all missing methods to the wrapped object.
+    #
+    # Creates delegator method for public methods of the wrapped object after
+    # first #method_missing hit to improve performance of following serializations.
+    #
+    def method_missing(name, ...) # rubocop:disable Style/MissingRespondToMissing -- base SimpleDelegator class has this method
+      result = super
+      self.class.define_delegator(name) if __getobj__.respond_to?(name)
+      result
+    end
+  end
+end

data/lib/serega/result_builder.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+class Serega
+  #
+  # Builds the serialized objects (Hash, Struct or Data) of one plan in one
+  # serialization mode.
+  #
+  # The builder gets the code of its `#call` and `#call_one` methods from
+  # SeregaResultCode. `#call` builds the serialized objects of a source group
+  # in one loop.
+  #
+  class SeregaResultBuilder # :nodoc:
+    # Serialization mode
+    attr_reader :mode
+
+    # Makes a result builder and generates its methods:
+    #
+    #   call(sources, context, batches, relations) -> Array<Hash, Struct, Data>
+    #
+    # - `batches` holds the loaded batches per point, or nil.
+    # - `relations` holds the relation values of all sources per relation
+    #   point, or nil.
+    #
+    # Points without relations and batch loaders get a `#call_one` method
+    # too, which builds the serialized object of one source:
+    #
+    #   call_one(source, context) -> Hash, Struct, Data
+    def initialize(serializer_class, mode, points)
+      @mode = mode
+      @points = points
+      @result_class = result_class(serializer_class)
+      # The generated code reads the `:const`, `:default` and formatter values from its constants
+      singleton_class.const_set(:SeregaAttributeValues, serializer_class::SeregaAttributeValues)
+      singleton_class.class_eval(SeregaResultCode.new(mode, points).to_s, SeregaUtils::SerializedAttributeError::GENERATED_CODE_FILE, 1)
+    end
+
+    private
+
+    def result_class(serializer_class)
+      return if mode == :hash
+
+      initialize_point = @points.find { |point| point.name == :initialize }
+      raise_member_error("Struct and Data can not have a member named initialize", initialize_point) if initialize_point
+
+      member_class(serializer_class, @points.map(&:name))
+    end
+
+    # Returns the Struct or Data class with the members. Raises a
+    # SeregaError for an attribute name that Ruby can not make a member.
+    def member_class(serializer_class, names)
+      (mode == :struct) ? serializer_class.struct_class_for(names) : serializer_class.data_class_for(names)
+    rescue ArgumentError, NameError => error
+      point = @points.find { |point| !member_name?(point.name) }
+      raise_member_error(error.message, point)
+    end
+
+    def member_name?(name)
+      (mode == :struct) ? Struct.new(name) : Data.define(name)
+      true
+    rescue ArgumentError, NameError
+      false
+    end
+
+    def raise_member_error(message, point)
+      SeregaUtils::SerializedAttributeError.call(SeregaError.new(message), point)
+    end
+  end
+end

data/lib/serega/result_code.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+class Serega
+  #
+  # Generates the Ruby code of the `SeregaResultBuilder#call` method of one
+  # plan in one serialization mode. The method reads all values of a source,
+  # then makes its serialized object in one step: a Hash literal,
+  # `Struct.new` or `Data.new`. The code reads plain attributes directly,
+  # for example `source.name`.
+  #
+  # Points without relations and batch loaders get a `#call_one(source,
+  # context)` method too. It returns the serialized object of one source,
+  # without the Array and the loop of `#call`.
+  #
+  # Generated code for a plan with `attribute :id` and
+  # `attribute :posts, serializer: PostSerializer` in the :hash mode:
+  #
+  #   def call(sources, context, batches, relations)
+  #     relation_values_1 = relations[@points[1]]
+  #     size = sources.size
+  #     serialized = Array.new(size)
+  #     source_index = 0
+  #     while source_index < size
+  #       source = sources[source_index]
+  #       value_0 =
+  #         begin
+  #           source.id
+  #         rescue => error
+  #           Serega::SeregaUtils::SerializedAttributeError.call(error, @points[0])
+  #         end
+  #       value_1 = relation_values_1[source_index]
+  #       serialized[source_index] = {:id => value_0, :posts => value_1}
+  #       source_index += 1
+  #     end
+  #     serialized
+  #   end
+  #
+  class SeregaResultCode # :nodoc:
+    # Method names called directly in generated code
+    PLAIN_METHOD_NAME = /\A[a-z_][a-zA-Z0-9_]*[?!]?\z/
+
+    # Serialization mode
+    attr_reader :mode
+
+    def initialize(mode, points)
+      @mode = mode
+      @points = points
+    end
+
+    # Returns the code of the `#call` method, and of the `#call_one`
+    # method for points without relations and batch loaders. The methods
+    # have local variables for the points, and they have the point index
+    # in their names:
+    # - `attribute_N` and `batches_N` read values with `SeregaAttribute#value`.
+    # - `conditions_N` checks the conditions of a conditional attribute.
+    # - `relation_values_N` holds the relation values of all sources.
+    # - `value_N` holds the value of the current source.
+    def to_s
+      variables = variables_code.join("\n  ")
+      values = values_code
+      code = call_code(variables, values)
+      return code unless @points.none? { |point| point.child_plan || !point.batch_loaders.empty? }
+
+      "#{code}\n#{call_one_code(variables, values)}"
+    end
+
+    private
+
+    def call_code(variables, values)
+      <<~RUBY
+        def call(sources, context, batches, relations)
+          #{variables}
+          size = sources.size
+          serialized = Array.new(size)
+          source_index = 0
+          while source_index < size
+            source = sources[source_index]
+            #{[*values, *build_serialized_code("serialized[source_index] = ")].join("\n").gsub("\n", "\n    ")}
+            source_index += 1
+          end
+          serialized
+        end
+      RUBY
+    end
+
+    def call_one_code(variables, values)
+      <<~RUBY
+        def call_one(source, context)
+          #{variables}
+          #{[*values, *build_serialized_code("")].join("\n").gsub("\n", "\n  ")}
+        end
+      RUBY
+    end
+
+    # Code that sets the local variables of a method: only the variables
+    # that the code of the points reads
+    def variables_code
+      point_variables = @points.each_with_index.flat_map { |point, index| point_variables_code(point, index) }
+      return point_variables if mode == :hash
+
+      ["result_class = @result_class", *point_variables]
+    end
+
+    def point_variables_code(point, index)
+      return ["relation_values_#{index} = relations[@points[#{index}]]"] if point.child_plan
+
+      variables = []
+      variables << "attribute_#{index} = @points[#{index}].attribute" unless point.attribute.value_method
+      variables << "batches_#{index} = batches[#{index}]" unless point.batch_loaders.empty?
+      variables << "conditions_#{index} = @points[#{index}].attribute.conditions" if point.conditional?
+      variables
+    end
+
+    # Code that reads all values of the source, one entry per point
+    def values_code
+      @points.each_with_index.map { |point, index| assign_value_code(point, index) }
+    end
+
+    # Code that assigns the value of the point to `value_N`. A conditional
+    # attribute gets SKIP when it fails its conditions. A conditional
+    # relation value is SKIP already.
+    def assign_value_code(point, index)
+      return "value_#{index} = #{read_value_code(point, index)}" if point.child_plan
+
+      read_code = rescued_read_code(point, index)
+      return "value_#{index} =\n#{read_code.gsub(/^/, "  ")}" unless point.conditional?
+
+      <<~RUBY.chomp
+        value_#{index} =
+          if conditions_#{index}.satisfy?(source, context)
+            value_#{index} =
+        #{read_code.gsub(/^/, "      ")}
+            conditions_#{index}.satisfy_value?(value_#{index}, context) ? value_#{index} : Serega::SeregaEngine::SKIP
+          else
+            Serega::SeregaEngine::SKIP
+          end
+      RUBY
+    end
+
+    # Code that reads the value of the point. An error raised there gets
+    # the attribute name. Only the rescue reads the point.
+    def rescued_read_code(point, index)
+      <<~RUBY.chomp
+        begin
+          #{read_value_code(point, index)}
+        rescue => error
+          Serega::SeregaUtils::SerializedAttributeError.call(error, @points[#{index}])
+        end
+      RUBY
+    end
+
+    # Code that reads the value of the point. A plain attribute reads its
+    # `:const`, `:default` and formatter values from the constants of
+    # SeregaAttributeValues.
+    def read_value_code(point, index)
+      return "relation_values_#{index}[source_index]" if point.child_plan
+
+      attribute = point.attribute
+      return attribute.value_code("source", "SeregaAttributeValues::") if attribute.value_method
+      return "attribute_#{index}.value(source, context)" if point.batch_loaders.empty?
+
+      "attribute_#{index}.value(source, context, batches: batches_#{index})"
+    end
+
+    # Code that builds the serialized object of the source. `assign` is the
+    # code that takes the serialized object, empty for the return value.
+    def build_serialized_code(assign)
+      return build_serialized_hash_code(assign) if mode == :hash
+
+      arguments = @points.each_index.map { |index| argument_code(index) }
+      ["#{assign}result_class.new(#{arguments.join(", ")})"]
+    end
+
+    # Code of the Struct or Data argument with the value of the point, nil
+    # for a skipped value
+    def argument_code(index)
+      return "value_#{index}" unless @points[index].conditional?
+
+      "(Serega::SeregaEngine::SKIP.equal?(value_#{index}) ? nil : value_#{index})"
+    end
+
+    # Code that builds the serialized Hash of the source, after `assign`.
+    # A Hash literal holds the values up to the first conditional value. Then
+    # the code adds the other values one by one, thus the Hash keys keep the
+    # order of the points.
+    def build_serialized_hash_code(assign)
+      literal_size = @points.index(&:conditional?) || @points.size
+      pairs = @points.first(literal_size).each_with_index.map { |point, index| "#{point.name.inspect} => value_#{index}" }
+      literal = "{#{pairs.join(", ")}}"
+      return ["#{assign}#{literal}"] if literal_size == @points.size
+
+      assigns = @points.each_with_index.drop(literal_size).map { |point, index| hash_assign_code(point, index) }
+      ["serialized_hash = #{literal}", *assigns, "#{assign}serialized_hash"]
+    end
+
+    # Code that adds the value of the point to the serialized Hash. It adds
+    # no key for a skipped value.
+    def hash_assign_code(point, index)
+      code = "serialized_hash[#{point.name.inspect}] = value_#{index}"
+      point.conditional? ? "#{code} unless Serega::SeregaEngine::SKIP.equal?(value_#{index})" : code
+    end
+  end
+end

data/lib/serega/shareable.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+class Serega
+  #
+  # Makes a serializer shareable between Ractors
+  #
+  class SeregaShareable # :nodoc:
+    class << self
+      # Makes the serializer definitions shareable between Ractors, except the
+      # plans cache. A definition that can not be shared stays as it is.
+      def call(serializer_class)
+        reasons = []
+
+        serializer_class.attributes.each_value do |attribute|
+          share(attribute, reasons) do |message|
+            "Attribute :#{attribute.name} of #{serializer_class} can not be shared between Ractors (#{attribute.location}): #{message}"
+          end
+        end
+
+        serializer_class.batch_loaders.each_value do |loader|
+          share(loader, reasons) { |message| "Batch loader :#{loader.name} of #{serializer_class} can not be shared between Ractors: #{message}" }
+        end
+
+        serializer_class.formatters.each do |name, formatter|
+          share(formatter, reasons) { |message| "Formatter :#{name} of #{serializer_class} can not be shared between Ractors: #{message}" }
+        end
+
+        (serializer_class.instance_variables - [:@plan_cache]).each do |name|
+          value = serializer_class.instance_variable_get(name)
+          share(value, reasons) { |message| "#{serializer_class} can not be shared between Ractors: #{message}" }
+        end
+
+        share_constants(serializer_class::SeregaAttributeValues, reasons)
+        reasons.first
+      end
+
+      private
+
+      def share_constants(values_class, reasons)
+        values_class.constants(false).each do |name|
+          share(values_class.const_get(name, false), reasons) { |message| "#{values_class} can not be shared between Ractors: #{message}" }
+        end
+      end
+
+      def share(value, reasons)
+        Ractor.make_shareable(value)
+      rescue Ractor::Error, ArgumentError => error
+        reasons << -yield(error.message)
+      end
+    end
+  end
+end

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