serega 0.42.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(:root) # => SeregaPlugins::Root
-      #
-      # @example Find plugin when providing plugin itself
-      #   SeregaPlugins.find_plugin(Root) # => Root
-      #
-      # @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

@@ -1,15 +1,13 @@
 # frozen_string_literal: true
 
 require "delegate"
-require "forwardable"
 
 class Serega
-  #
-  # Wraps the serialized object, so computed attribute values can be defined as
+  # 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 serialized object are available directly inside presenter methods.
+  # - 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).
@@ -18,7 +16,6 @@ class Serega
   # The `presenter do ... end` block is evaluated inside the serializer's own
   # SeregaPresenter class, so multiple blocks accumulate.
   #
-  # @example
   #   class UserSerializer < Serega
   #     attribute :name
   #     attribute :role
@@ -33,13 +30,60 @@ class Serega
   #       end
   #     end
   #   end
-  #
-  # @private
-  class SeregaPresenter < SimpleDelegator
+  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
+
     #
-    # @param object [Object] Serialized object to wrap
-    # @param ctx [Hash, nil] Serialization context
+    # 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
@@ -50,17 +94,15 @@ class Serega
     attr_reader :__ctx__
 
     #
-    # Delegates all missing methods to serialized object.
+    # Delegates all missing methods to the wrapped object.
     #
-    # Creates delegator method after first #method_missing hit to improve
-    # performance of following serializations.
+    # 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, *_args, &_block) # rubocop:disable Style/MissingRespondToMissing -- base SimpleDelegator class has this method
-      super.tap do
-        self.class.def_delegator :__getobj__, name
-      end
+    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
-
-    extend Forwardable
   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