panko_serializer 0.8.5 → 1.0.0

data/lib/panko/code_gen/generators/fanout.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Panko::CodeGen
+  module Generators
+    # Mutual-recursion peers +require_relative+ each other. Ruby allows this because
+    # a peer's constant is read only when a method runs, after both files have loaded.
+    module Fanout
+      module_function
+
+      def emit_files(descriptor, output:, config:)
+        cyclic_ids = CycleMembership.cyclic_descriptor_ids(descriptor)
+        DescriptorWalk.in_emit_order(descriptor).map do |desc|
+          {
+            descriptor: desc,
+            basename: basename_for(desc, output),
+            source: build_file(desc, output, config, cyclic_ids)
+          }
+        end
+      end
+
+      def basename_for(descriptor, output)
+        "#{snake_case(descriptor.name)}_#{output}.rb"
+      end
+
+      def snake_case(camel)
+        camel.gsub(/(?<=.)([A-Z])/, '_\1').downcase
+      end
+      private_class_method :snake_case
+
+      def build_file(descriptor, output, config, cyclic_ids)
+        builder = CodeBuilder.new
+        builder.line "# frozen_string_literal: true"
+        builder.blank
+        Banner.emit(builder, descriptor, output: output, config: config)
+        deps = ordered_dependencies(descriptor)
+        deps.each do |dep|
+          builder.line %(require_relative "#{snake_case(dep.name)}_#{output}")
+        end
+        builder.blank if deps.any?
+        emitter = ClassEmitter.new(Panko::CodeGen::Generator.sink_for(output))
+        emitter.emit_class(descriptor, config, builder, cyclic_ids)
+        builder.to_s + "\n"
+      end
+      private_class_method :build_file
+
+      # Seeded with +descriptor+ itself: a self-loop needs no +require_relative+.
+      def ordered_dependencies(descriptor)
+        seen = {descriptor.__id__ => true}
+        deps = []
+        descriptor.associations.flat_map(&:descriptors).each do |target|
+          next if seen[target.__id__]
+          seen[target.__id__] = true
+          deps << target
+        end
+        deps
+      end
+      private_class_method :ordered_dependencies
+    end
+  end
+end

data/lib/panko/code_gen/generators/field_index.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Panko::CodeGen
+  module Generators
+    # Indexes are written into each Field's +filters.drops?(N)+ check, so
+    # filtering a Field costs one Array lookup instead of a Hash lookup.
+    module FieldIndex
+      module_function
+
+      # Look indexes up by +GeneratedNames.filter_key+, never by position:
+      # {FieldWalk} emits Associations before Method Attributes.
+      def build(descriptor)
+        index = {}
+        i = 0
+        fields = descriptor.attributes + descriptor.method_attributes + descriptor.associations
+        fields.each do |field|
+          index[GeneratedNames.filter_key(field)] = i
+          i += 1
+        end
+        index
+      end
+
+      # The +name: N+ shorthand parses only for identifier-style names.
+      def to_hash_literal(field_index)
+        return "{}" if field_index.empty?
+        pairs = field_index.map { |name, idx| "#{name}: #{idx}" }
+        "{#{pairs.join(", ")}}"
+      end
+    end
+  end
+end

data/lib/panko/code_gen/generators/field_walk.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Panko::CodeGen
+  module Generators
+    # Both Record-access strategies and both output modes share this walk,
+    # so field order and filter indexes cannot differ between them.
+    module FieldWalk
+      module_function
+
+      # +attribute_emit+ lets the Specialized strategy pick each Attribute's
+      # read from the Model's column metadata instead of one +read_expr+ for all.
+      def emit_fields(descriptor, config, field_index, builder, sink, read_expr:, attribute_emit: nil)
+        sink.open_record(builder)
+        descriptor.attributes.each do |attribute|
+          index = field_index.fetch(GeneratedNames.filter_key(attribute))
+          if attribute_emit
+            attribute_emit.call(attribute, index)
+          else
+            sink.attribute(attribute, read_expr.call(attribute.source), config, index, builder)
+          end
+        end
+        descriptor.associations.each do |association|
+          sink.association(
+            association, read_expr.call(association.source), config,
+            field_index.fetch(GeneratedNames.filter_key(association)), builder
+          )
+        end
+        descriptor.method_attributes.each do |method_attribute|
+          sink.method_attribute(
+            method_attribute, config,
+            field_index.fetch(GeneratedNames.filter_key(method_attribute)), builder
+          )
+        end
+        sink.close_record(builder)
+      end
+    end
+  end
+end

data/lib/panko/code_gen/generators/generated_names.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Panko::CodeGen
+  module Generators
+    # Names that generated source and the emitters must agree on, kept here
+    # so a rename edits one method.
+    module GeneratedNames
+      module_function
+
+      def class_name(descriptor, suffix)
+        "#{descriptor.name}_#{suffix}"
+      end
+
+      def serializer_ivar(association)
+        "@#{association.name}_serializer"
+      end
+
+      def variant_serializer_ivar(association, index)
+        "#{serializer_ivar(association)}_#{index}"
+      end
+
+      def callable_ivar(method_attribute)
+        "@cb_#{method_attribute.name}"
+      end
+
+      def if_guard_ivar(association)
+        "@cb_if_#{association.name}"
+      end
+
+      def write_one
+        "_write_one"
+      end
+
+      def to_hash
+        "_to_hash"
+      end
+
+      def generic_write_one
+        "_generic_write_one"
+      end
+
+      def generic_to_hash
+        "_generic_to_hash"
+      end
+
+      def write_one_hash
+        "_write_one_hash"
+      end
+
+      def write_one_object
+        "_write_one_object"
+      end
+
+      def to_hash_hash
+        "_to_hash_hash"
+      end
+
+      def to_hash_object
+        "_to_hash_object"
+      end
+
+      def field_index_const
+        "FIELD_INDEX"
+      end
+
+      # Associations are keyed by Source, not output name, because nested
+      # filters are looked up by Source (+Filter::Indexed#child+).
+      def filter_key(field)
+        field.is_a?(Association) ? field.source : field.name
+      end
+    end
+  end
+end

data/lib/panko/code_gen/generators/hash_sink.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+module Panko::CodeGen
+  module Generators
+    # Values go through +Panko::CodeGen.cast_datetime+ so Hash mode matches what
+    # Oj's +:rails+ mode does to them in JSON mode.
+    class HashSink < Sink
+      def output
+        :hash
+      end
+
+      def suffix
+        "Hash"
+      end
+
+      def entry_name
+        GeneratedNames.to_hash
+      end
+
+      def generic_entry_name
+        GeneratedNames.generic_to_hash
+      end
+
+      def split_hash_helper
+        GeneratedNames.to_hash_hash
+      end
+
+      def split_object_helper
+        GeneratedNames.to_hash_object
+      end
+
+      def entry_params
+        "record, context, scope, filters"
+      end
+
+      # Hash mode needs no constants beyond +FIELD_INDEX+.
+      def emit_class_constants(descriptor, config, builder)
+      end
+
+      def emit_serialize_one(config, builder)
+        signature = config.supports_root_key ?
+          "def serialize_one(record, context: nil, scope: nil, filters: nil, root_key: nil)" :
+          "def serialize_one(record, context: nil, scope: nil, filters: nil)"
+        builder.line signature
+        builder.indent do
+          builder.line "filters = Panko::CodeGen::Filter.wrap(filters, #{GeneratedNames.field_index_const})"
+          if config.supports_root_key
+            builder.line "validate_root_key!(root_key)"
+            builder.line "result = #{GeneratedNames.to_hash}(record, context, scope, filters)"
+            builder.line "root_key ? {root_key => result} : result"
+          else
+            builder.line "#{GeneratedNames.to_hash}(record, context, scope, filters)"
+          end
+        end
+        builder.line "end"
+      end
+
+      def emit_serialize_many(config, builder)
+        signature = config.supports_root_key ?
+          "def serialize_many(records, context: nil, scope: nil, filters: nil, root_key: nil)" :
+          "def serialize_many(records, context: nil, scope: nil, filters: nil)"
+        builder.line signature
+        builder.indent do
+          builder.line "filters = Panko::CodeGen::Filter.wrap(filters, #{GeneratedNames.field_index_const})"
+          if config.supports_root_key
+            builder.line "validate_root_key!(root_key)"
+            builder.line "result = records.map { |r| #{GeneratedNames.to_hash}(r, context, scope, filters) }"
+            builder.line "root_key ? {root_key => result} : result"
+          else
+            builder.line "records.map { |r| #{GeneratedNames.to_hash}(r, context, scope, filters) }"
+          end
+        end
+        builder.line "end"
+      end
+
+      def open_record(builder)
+        builder.line "result = {}"
+      end
+
+      def close_record(builder)
+        builder.line "result"
+      end
+
+      # +cast: false+ skips +cast_datetime+ when the column type proves the cast would
+      # return the value unchanged; the wrapper otherwise runs on every write.
+      def attribute(attribute, read_expr, config, index, builder, cast: true)
+        value_expr = cast ? "Panko::CodeGen.cast_datetime(#{read_expr})" : read_expr
+        builder.line "unless filters.drops?(#{index})"
+        builder.indent do
+          builder.line "result[#{key_literal(attribute.name, config)}] = #{value_expr}"
+        end
+        builder.line "end"
+      end
+
+      def specialized_attribute(attribute, ar_model, config, index, builder)
+        if RecordAccess::Specialized.datetime_column_attribute?(attribute, ar_model)
+          datetime_column_attribute(attribute, config, index, builder)
+        else
+          attribute(
+            attribute,
+            RecordAccess::Specialized.attribute_read_expr(attribute, ar_model),
+            config,
+            index,
+            builder,
+            cast: !RecordAccess::Specialized.plain_column_attribute?(attribute, ar_model)
+          )
+        end
+      end
+
+      def method_attribute(method_attribute, config, index, builder)
+        builder.line "unless filters.drops?(#{index})"
+        builder.indent do
+          builder.line "value = #{method_attribute_call_expression(method_attribute)}"
+          builder.line "unless value.equal?(Panko::CodeGen::SKIP)"
+          builder.indent do
+            builder.line "result[#{key_literal(method_attribute.name, config)}] = Panko::CodeGen.cast_datetime(value)"
+          end
+          builder.line "end"
+        end
+        builder.line "end"
+      end
+
+      def association(association, source_read_expr, config, index, builder)
+        key_lit = key_literal(association.name, config)
+        builder.line "unless filters.drops?(#{index})"
+        builder.indent do
+          with_if_guard(association, builder) do
+            case association.kind
+            when :has_one
+              builder.line "value = #{source_read_expr}"
+              if config.null_for_missing_has_one
+                has_one_default(association, key_lit, builder)
+              else
+                has_one_omit(association, key_lit, builder)
+              end
+            when :has_many
+              has_many(association, source_read_expr, key_lit, builder)
+            end
+          end
+        end
+        builder.line "end"
+      end
+
+      private
+
+      def key_literal(name, config)
+        case config.hash_output_key_type
+        when :symbol then ":#{name}"
+        else %("#{name}")
+        end
+      end
+
+      def has_one_default(association, key_lit, builder)
+        builder.line "result[#{key_lit}] = if value.nil?"
+        builder.indent { builder.line "nil" }
+        builder.line "else"
+        builder.indent do
+          child_write(association, "value", builder) do |ivar|
+            "#{ivar}.#{GeneratedNames.to_hash}(value, context, scope, #{child_filter_expr(association)})"
+          end
+        end
+        builder.line "end"
+      end
+
+      def has_one_omit(association, key_lit, builder)
+        builder.line "unless value.nil?"
+        builder.indent do
+          if association.variants.empty?
+            builder.line "result[#{key_lit}] = #{GeneratedNames.serializer_ivar(association)}." \
+              "#{GeneratedNames.to_hash}(value, context, scope, #{child_filter_expr(association)})"
+          else
+            builder.line "result[#{key_lit}] = begin"
+            builder.indent do
+              child_write(association, "value", builder) do |ivar|
+                "#{ivar}.#{GeneratedNames.to_hash}(value, context, scope, #{child_filter_expr(association)})"
+              end
+            end
+            builder.line "end"
+          end
+        end
+        builder.line "end"
+      end
+
+      # +child_filter+ is looked up once per record, not once per element.
+      def has_many(association, source_read_expr, key_lit, builder)
+        builder.line "child_filter = #{child_filter_expr(association)}"
+        if association.variants.empty?
+          builder.line(
+            "result[#{key_lit}] = #{source_read_expr}.map { |element| " \
+              "#{GeneratedNames.serializer_ivar(association)}.#{GeneratedNames.to_hash}(element, context, scope, child_filter) }"
+          )
+          return
+        end
+        builder.line "result[#{key_lit}] = #{source_read_expr}.map do |element|"
+        builder.indent do
+          child_write(association, "element", builder) do |ivar|
+            "#{ivar}.#{GeneratedNames.to_hash}(element, context, scope, child_filter)"
+          end
+        end
+        builder.line "end"
+      end
+
+      # +format_raw+ returns nil for raw values it cannot format; the typed-read
+      # fallback then goes through +cast_datetime+ so a Time still becomes a String.
+      def datetime_column_attribute(attribute, config, index, builder)
+        source_lit = %("#{attribute.source}")
+        builder.line "unless filters.drops?(#{index})"
+        builder.indent do
+          builder.line "value = Panko::CodeGen::DateTimeFormat.format_raw(record.read_attribute_before_type_cast(#{source_lit}))"
+          builder.line "result[#{key_literal(attribute.name, config)}] = value || " \
+            "Panko::CodeGen.cast_datetime(record._read_attribute(#{source_lit}))"
+        end
+        builder.line "end"
+      end
+    end
+  end
+end