graph_weaver 0.6.0 → 0.7.0

data/lib/graph_weaver/codegen/nodes.rb

@@ -158,8 +158,12 @@ class GraphWeaver::Codegen
       else
         "#{var}&.then { |v#{depth + 1}| #{@of.hash_coerce("v#{depth + 1}", depth + 2)} }"
       end
+      return "#{expr}.map { |#{var}| #{inner} }" if hash_coerce_identity?
 
-      "#{expr}.map { |#{var}| #{inner} }"
+      # the index is a path segment — `where._and.0._not.species` needs the 0
+      # to name one form field
+      idx = "i#{depth}"
+      "#{expr}.map.with_index { |#{var}, #{idx}| GraphWeaver::InputStruct.element(#{idx}, #{var}) { #{inner} } }"
     end
 
     def hash_coerce_identity? = @of.hash_coerce_identity?
@@ -190,6 +194,11 @@ class GraphWeaver::Codegen
       "#{class_name}.from_h(#{expr})"
     end
 
+    # a composite renders itself — #as_json is the mirror of .from_h
+    def serialize(expr, _depth)
+      "#{expr}.as_json"
+    end
+
     def nested = self
   end
 
@@ -253,8 +262,16 @@ class GraphWeaver::Codegen
       end
     end
 
+    # The fallback member is in no wire table — several wire values collapse
+    # into it, so `invert` keeps none — and it is exactly the member a drifted
+    # response casts to. Its own #serialize is the only spelling left, and it
+    # casts back to the fallback, so a result still round-trips through
+    # #as_json. Without a fallback the table is total and a miss is a real
+    # mistake, so it still raises.
     def serialize(expr, _depth)
-      "#{const_prefix}_TO_WIRE.fetch(#{expr})"
+      return "#{const_prefix}_TO_WIRE.fetch(#{expr})" unless @fallback
+
+      "#{const_prefix}_TO_WIRE.fetch(#{expr}) { |member| member.serialize }"
     end
 
     def leaf? = true
@@ -298,6 +315,8 @@ class GraphWeaver::Codegen
       end
     end
 
+    def serialize(expr, depth) = @of.serialize(expr, depth)
+    def serialize_identity? = @of.serialize_identity?
     def nested = @of
   end
 
@@ -306,10 +325,13 @@ class GraphWeaver::Codegen
     # alphabetically first of their keys, which the walk may reach second
     attr_accessor :class_name
     attr_reader :members # graphql type name => ObjectNode
-    # the struct an unnamed (or newly-added) __typename deserializes into
+    # The struct an unnamed (or newly-added) __typename deserializes into.
+    # Required, not defaulted: a dispatch without one has to refuse a member
+    # the schema grew, and "the query named every member today" is not a
+    # reason to break tomorrow's response.
     attr_reader :catch_all
 
-    def initialize(class_name, members, catch_all = nil)
+    def initialize(class_name, members, catch_all)
       @class_name = class_name
       @members = members
       @catch_all = catch_all
@@ -321,6 +343,10 @@ class GraphWeaver::Codegen
       "#{class_name}.from_h(#{expr})"
     end
 
+    def serialize(expr, _depth)
+      "#{expr}.as_json"
+    end
+
     def nested = self
   end
 
@@ -342,6 +368,10 @@ class GraphWeaver::Codegen
     def cast(expr, _depth)
       "#{class_name}.from_h(#{expr})"
     end
+
+    def serialize(expr, _depth)
+      "#{expr}.as_json"
+    end
   end
 
   # An input-object variable: emitted as a module-level T::Struct whose
@@ -351,14 +381,17 @@ class GraphWeaver::Codegen
   class InputNode < Node
     Field = Struct.new(:prop, :wire, :node, :required)
 
-    attr_reader :class_name, :fields
+    # graphql_name as well as class_name: a schema coordinate is spelled the
+    # schema's way (pokemon_bool_exp.name), which camelize has already lost.
+    attr_reader :class_name, :graphql_name, :fields
     # @oneOf: exactly one field may be supplied. The schema can't say so — every
     # @oneOf field is nullable — so the generated struct carries the flag and
     # InputStruct#serialize enforces it.
     attr_accessor :one_of
 
-    def initialize(class_name)
+    def initialize(class_name, graphql_name = class_name)
       @class_name = class_name
+      @graphql_name = graphql_name
       @fields = []
       @one_of = false
     end

data/lib/graph_weaver/codegen/registry.rb

@@ -0,0 +1,175 @@
+# typed: true
+# frozen_string_literal: true
+
+# One graph's registrations: the scalar codecs, the enum mappings, and the
+# type helpers a generation reads. The three tables move together because a
+# registration is scoped to the schema it describes — an app with two schemas
+# registers `Money` for each, or for only one, and neither answer is the
+# other's (see GraphWeaver.graph).
+#
+# The methods themselves live in Registrations, which the three codegen/*.rb
+# files fill in; this is where they get somewhere to write. Codegen's class
+# methods (GraphWeaver.register_scalar and friends) delegate here, to the
+# default graph's registry — so a single-schema app never meets this class.
+
+class GraphWeaver::Codegen
+  # The registrations one graph generates with: the scalar codecs, the enum
+  # mappings and the type helpers, plus what a schema can say about them.
+  # Not API (private_constant below) — an app writes register_scalar/
+  # register_enum/extend_type, at the top level (the default graph) or in a
+  # graph block, and never names the object holding them.
+  # codegen/{scalar,enum,type_helpers}.rb fill in the registering half.
+  class Registry
+    # What a registry's names must be in the schema. extend_type decorates
+    # whatever composite a query reaches, so it demands no particular kind.
+    REGISTERED_KIND = { "scalar" => "SCALAR", "enum" => "ENUM" }.freeze
+    # the type registry is reached via extend_type; scalars/enums via register_*
+    REGISTRATION_METHOD = { "type" => "extend_type", "scalar" => "register_scalar", "enum" => "register_enum" }.freeze
+    private_constant :REGISTERED_KIND, :REGISTRATION_METHOD
+
+    # Every registration this schema can't match, one sentence each. The answer
+    # depends on the schema and the registry alone, not on any one document, so
+    # a whole generate! run gets the same list — which is what lets the build
+    # report it once (see GraphWeaver.unmatched_registrations).
+    #
+    # The built-in scalars are pre-registered entries in the same table rather
+    # than user intent, so they're exempt — a schema with no Date scalar is not
+    # a mistake.
+    def unmatched_registrations(schema)
+      {
+        "enum" => enum_registry,
+        "scalar" => scalar_registry.except(*BUILTIN_SCALARS),
+        "type" => type_registry,
+      }.flat_map do |kind, registry|
+        registry.keys.filter_map { |name| validate_registration!(schema, kind, name) }
+      end
+    end
+
+    # A registry serves one graph, but a generation sees one schema — so a
+    # registration fails generation only where THIS schema can disprove it: a
+    # name it declares as something else, or a coordinate whose field it declares
+    # as a composite. A name it can't match at all proves nothing, because an
+    # entity type is declared by every subgraph that references it while its
+    # fields are split among them; that returns the sentence to say instead.
+    def validate_registration!(schema, kind, name)
+      method = REGISTRATION_METHOD.fetch(kind)
+      # register_scalar("Type.field", ...) overrides one field's scalar — validate
+      # the field, not that a type named "Type.field" exists.
+      return validate_scalar_field!(schema, name, method) if kind == "scalar" && name.include?(".")
+
+      type = schema.get_type(name)
+      unless type
+        return unmatched(schema, method, name, kind, GraphWeaver::Internal::Util.did_you_mean(schema.types.keys, name))
+      end
+
+      expected = REGISTERED_KIND[kind]
+      return if expected.nil? || type.kind.name == expected
+
+      found = type.kind.name.downcase.tr("_", " ")
+      # a leaf registered as the other kind has a method that would have worked
+      other = REGISTERED_KIND.key(type.kind.name)
+      raise GraphWeaver::Error,
+        "#{method}(#{name.inspect}) names #{article(found)} #{found}, not #{article(kind)} " \
+        "#{kind}#{other ? " — use #{REGISTRATION_METHOD.fetch(other)}" : ""}"
+    end
+    private :validate_registration!
+
+    # A per-field override, register_scalar("Type.field", ...). Neither an absent
+    # type nor an absent field is disprovable here; what is, is a field this
+    # schema declares as something a scalar codec could never read.
+    def validate_scalar_field!(schema, name, method)
+      type_name, field_name = name.split(".", 2)
+      type = schema.get_type(type_name)
+      unless type
+        near = GraphWeaver::Internal::Util.did_you_mean(schema.types.keys, type_name)
+        return unmatched(schema, method, name, "scalar field", near && "#{near}.#{field_name}")
+      end
+
+      fields = type.respond_to?(:fields) ? type.fields : {}
+      field = fields[field_name]
+      unless field
+        near = GraphWeaver::Internal::Util.did_you_mean(fields.keys, field_name)
+        return unmatched(schema, method, name, "scalar field", near && "#{type_name}.#{near}")
+      end
+      return if field.type.unwrap.kind.name == "SCALAR"
+
+      raise GraphWeaver::Error,
+        "#{method}(#{name.inspect}): #{name} isn't a scalar field (it's #{field.type.unwrap.kind.name.downcase})"
+    end
+    private :validate_scalar_field!
+
+    # What to say about a name this schema has nothing for. Registrations are
+    # graph-scoped — federation composes by name, so one `Money` codec serves
+    # every subgraph that declares it — which is exactly why this schema can't
+    # tell a typo from a registration for the subgraph next door. Say both.
+    def unmatched(schema, method, name, what, suggestion)
+      hint = suggestion ? " (did you mean '#{suggestion}'?)" : ""
+      "#{method}(#{name.inspect}) matches no #{what} in #{schema.name || "this schema"} " \
+        "— a typo#{hint}, or a registration for another schema"
+    end
+    private :unmatched
+
+    def article(word) = GraphWeaver::Internal::Util.article(word)
+    private :article
+
+    # Every table back to its starting state — scalars (built-ins restored),
+    # enum mappings, and type helpers. The clean slate between tests, and the
+    # one call that stays right when a fourth kind of registration shows up.
+    def reset_registrations!
+      reset_scalars!
+      reset_enums!
+      reset_type_helpers!
+      self
+    end
+
+    def initialize = register_builtin_scalars!
+
+    # A graph starts from the top-level registrations and adds its own, so the
+    # three tables are copied rather than shared — an app that registered Money
+    # before it had a second schema keeps it, and a graph block can't reach back.
+    def initialize_copy(other)
+      super
+      @scalar_registry = other.scalar_registry.dup
+      @enum_registry = other.enum_registry.dup
+      # the entry is a hash of mutable arrays, so each one is copied too
+      @type_registry = other.type_registry.transform_values { |e| e.transform_values(&:dup) }
+      @helper_counts = other.send(:helper_counts).dup
+    end
+  end
+
+  # The default graph's registrations — where a top-level
+  # GraphWeaver.register_scalar writes, and what a generation uses unless a
+  # graph hands it its own.
+  def self.registry = @registry ||= Registry.new
+
+  # Pre-registered rather than user intent, so generation doesn't hold a schema
+  # to them (validate_registration! skips these). Read off a fresh registry: a
+  # seventh built-in shouldn't have to be named twice.
+  BUILTIN_SCALARS = Registry.new.scalar_registry.keys.freeze
+
+  class << self
+    # The default graph's registry answers every one of these — the surface an
+    # app has used since before graphs existed, unchanged.
+    def register_scalar(...) = registry.register_scalar(...)
+    def register_enum(...) = registry.register_enum(...)
+    def extend_type(...) = registry.extend_type(...)
+    def scalar(...) = registry.scalar(...)
+    def scalar_registry = registry.scalar_registry
+    def enum_registry = registry.enum_registry
+    def type_registry = registry.type_registry
+    def unmatched_registrations(...) = registry.unmatched_registrations(...)
+    def clear_scalars! = registry.clear_scalars! && self
+    def reset_scalars! = registry.reset_scalars! && self
+    def reset_enums! = registry.reset_enums! && self
+    def reset_type_helpers! = registry.reset_type_helpers! && self
+
+    # Returns Codegen, not the registry: these are the documented calls, and
+    # their value has always been something you can keep chaining off.
+    def reset_registrations! = registry.reset_registrations! && self
+  end
+
+  # Nothing outside the gem names it, and it can't move under Internal either:
+  # its methods build a ScalarType and an EnumType, which are private here.
+  # Private at load, not in a method body — see spec/registry_spec.rb.
+  private_constant :Registry
+end

data/lib/graph_weaver/codegen/scalar_type.rb

@@ -12,10 +12,12 @@ class GraphWeaver::Codegen
   # scalars and overrides go through the same path.
   #
   # cast/serialize normalize to procs that, given a Ruby expression string,
-  # return the code to inline. Left nil (the default) they are inferred
-  # from the Ruby type when it is a real class, by probing for a known
-  # deserializer and pairing its serializer (see CODECS) — so the common
-  # case needs no more than a class:
+  # return the code to inline. Left nil (the default) they are inferred from
+  # the Ruby type: a type the library already knows takes its codec from
+  # STDLIB, otherwise it is probed for a known deserializer whose serializer
+  # pairs with it (see CODECS), and failing that for a Kernel conversion
+  # function of its own name — so the common case needs no more than a class:
+  #      type: BigDecimal (Kernel#BigDecimal) => BigDecimal(expr) / expr.to_s("F")
   #      type: Money   (defines .parse)   => Money.parse(expr) / expr.to_s
   #      type: Blob    (defines .load)    => Blob.load(expr)   / Blob.dump(expr)
   # Probing the *deserialize* side is deliberate: every object has #to_s,
@@ -25,6 +27,7 @@ class GraphWeaver::Codegen
   #   - a Symbol names a method, so there is no string to misspell:
   #           cast: :load        => "Blob.load(expr)"    (class method on type)
   #           serialize: :to_json => "expr.to_json"      (instance method)
+  #   - an Array is that method with arguments: serialize: [:to_s, "F"]
   #   - a Proc handles anything a Symbol can't express:
   #           cast: ->(e) { "Money.new(#{e})" }
   #   - :itself opts out — force identity pass-through even when a codec
@@ -49,17 +52,55 @@ class GraphWeaver::Codegen
         ->(klass, value) { klass.dump(value) }),
     ].freeze
 
-    # A scalar with no `cast:` to run input through: its Ruby type is the
-    # whole rule, so key on that — a custom scalar registered as a plain
-    # String gets the same check. ID is the exception GraphQL itself names
-    # (see Coerce.id), matched by GraphQL name in #coercer.
+    # A scalar whose registration named no `cast:` of its own: its Ruby type
+    # is the whole rule, so key on that — a custom scalar registered as a
+    # plain String gets the same check. ID is the exception GraphQL itself
+    # names (see Coerce.id), matched by GraphQL name in #coercer.
     COERCERS = {
       "Integer" => "integer",
       "Float" => "float",
       "String" => "string",
       "T::Boolean" => "boolean",
+      "Date" => "date",
+      "Time" => "time",
     }.freeze
-    private_constant :Codec, :CODECS, :COERCERS
+
+    # What the library already knows about a Ruby type, so registering one
+    # takes nothing but the class. Consulted only where the registration is
+    # silent; an explicit cast:/serialize:/requires: wins. Two things the
+    # probe above can't work out on its own:
+    #   - the wire spelling. BigDecimal#to_s writes "0.125e2", which is not
+    #     what any server means by 12.5, and Date.parse reads a great deal
+    #     more than the ISO 8601 a Date scalar carries.
+    #   - the file to require, so the generated source stands alone.
+    # Only types whose wire form is unambiguous belong here.
+    #
+    # `call:` is the runnable twin of a Proc `serialize:`, which builds source
+    # and so can't be run — the testing harness needs both (see
+    # #serialize_value).
+    TIMESTAMP = ->(expr) { "GraphWeaver::Coerce.timestamp(#{expr})" }
+    TIMESTAMP_CALL = ->(value) { GraphWeaver::Coerce.timestamp(value) }
+
+    STDLIB = {
+      "BigDecimal" => { serialize: [:to_s, "F"], requires: "bigdecimal" },
+      # JSON has one number type, so a whole Float arrives as `1` from every
+      # encoder that drops the trailing zero (graphql-js and Go both do)
+      "Float" => { cast: ->(expr) { "GraphWeaver::Coerce.float(#{expr})" } },
+      # strftime, not #iso8601: DateTime < Date passes the is_a? guard, and its
+      # #iso8601 writes a timestamp where the schema said a date goes
+      "Date" => { cast: :iso8601, serialize: [:strftime, "%F"], requires: "date" },
+      # #iso8601 takes no precision, so it writes whole seconds and a
+      # sub-second timestamp goes back out poorer than it came in
+      "Time" => { cast: :parse, serialize: TIMESTAMP, call: TIMESTAMP_CALL, requires: "time" },
+      "DateTime" => { cast: :iso8601, serialize: TIMESTAMP, call: TIMESTAMP_CALL, requires: "date" },
+    }.freeze
+
+    # Everything JSON.parse can hand back. A registered type outside this set
+    # has to be BUILT from one of them, which is what a cast is for (and what
+    # Codegen#refuse_uncastable! insists on).
+    WIRE_CLASSES = [String, Integer, Float, Hash, Array, TrueClass, FalseClass].freeze
+
+    private_constant :Codec, :CODECS, :COERCERS, :STDLIB
 
     attr_reader :graphql_name, :type, :requires
 
@@ -67,14 +108,25 @@ class GraphWeaver::Codegen
       @graphql_name = graphql_name.to_s
       @klass = type.is_a?(Module) ? type : nil
       @type = type_name(type)
-      # requires: load BEFORE codec probing — the probe method may come
-      # from the required file (core Time has no .parse until the "time"
-      # stdlib loads)
-      @requires = normalize_requires(requires)
+      known = STDLIB[@type] || {}
+      # requires: load BEFORE probing — the deserializer may arrive with the
+      # file (core Time has no .parse until the "time" stdlib loads, and
+      # Kernel#BigDecimal none until "bigdecimal" does). A path from STDLIB
+      # is the library's own, so it loads even for a type: given as a String,
+      # whose dependency we otherwise can't assume is installed.
+      @requires =
+        if requires.nil?
+          GraphWeaver::Codegen.normalize_requires!(known[:requires], load: true)
+        else
+          GraphWeaver::Codegen.normalize_requires!(requires, load: !@klass.nil?)
+        end
+      @cast_given = cast unless cast == :itself
       codec = @klass && CODECS.find { |c| @klass.respond_to?(c.probe) }
-      @cast = normalize_cast(cast, codec&.cast)
-      @serialize = normalize_serialize(serialize, codec&.serialize)
-      @serialize_value = runtime_serialize(serialize, codec)
+      @cast = normalize_cast(cast || known[:cast], codec&.cast || kernel_cast)
+      @serialize = normalize_serialize(serialize || known[:serialize], codec&.serialize)
+      @serialize_value = (known[:call] if serialize.nil?) ||
+        runtime_serialize(serialize || known[:serialize], codec)
+      warn_half_a_value_object
     end
 
     def cast(expr) = @cast&.call(expr)
@@ -95,21 +147,74 @@ class GraphWeaver::Codegen
 
     # The code that normalizes a loose input — a Rails param — into this
     # scalar's Ruby type before it is serialized, or nil for nothing to do.
-    # `cast:` is the how: it already knows how to build the Ruby object from
-    # a wire value, guarded so an already-typed value passes through. A
-    # scalar without one falls back to its Ruby type's check, which is what
-    # `.checked(:never)` on the generated sig gives up.
+    # The Ruby type's own rule in Coerce is the check, which is what
+    # `.checked(:never)` on the generated sig gives up. A registration that
+    # named its own `cast:` says how to build the Ruby object instead — but
+    # the guard in front of it and the verdict when it refuses are still the
+    # library's, so both go through Coerce.cast rather than a bare `is_a?`
+    # (a DateTime is one of those, and is not a Date on any wire).
+    # The schema's name for the scalar travels with the value, so a refusal
+    # reports GraphQL vocabulary rather than the Ruby type it maps to —
+    # register_scalar("Money", BigDecimal) refuses a Money, not a BigDecimal.
     def coerce_input(expr)
-      if cast?
-        "(#{expr}.is_a?(#{@type}) ? #{expr} : #{cast(expr)})"
-      elsif (fn = coercer)
-        "GraphWeaver::Coerce.#{fn}(#{expr})"
+      if (fn = coercer)
+        "GraphWeaver::Coerce.#{fn}(#{expr}, #{@graphql_name.inspect})"
+      elsif cast?
+        "GraphWeaver::Coerce.cast(#{@type}, #{expr}, #{@graphql_name.inspect}) { |raw| #{cast("raw")} }"
+      end
+    end
+
+    # Why this registration can't read the JSON at `where`, and what to do about
+    # it. Two different mistakes land here, so say which: a type: given by name
+    # was never probed (there is no class in hand to probe), while a class was
+    # probed and matched nothing. Raised by Codegen#refuse_uncastable!, which
+    # owns the question of whether the wire could satisfy the prop at all.
+    def uncastable_message(where)
+      article = GraphWeaver::Internal::Util.article(@type)
+      head = "register_scalar(#{@graphql_name.inspect}, #{@klass ? @type : @type.inspect}) has no " \
+        "cast, so nothing builds #{article} #{@type} out of the JSON at #{where}"
+      if @klass.nil?
+        "#{head} — a type: given by name is never probed, since there is no class in hand. Pass " \
+          "the class (register_scalar(#{@graphql_name.inspect}, #{@type})) to infer a cast from " \
+          "it, or name one yourself (cast: :parse names a class method, " \
+          "cast: ->(v) { \"#{@type}.parse(\#{v})\" } emits any expression)"
+      else
+        "#{head} — #{@type} defines no .parse and no .load, and Kernel has no #{@type} conversion " \
+          "function, so there was nothing to infer. Give it a cast (cast: :parse names a class " \
+          "method, cast: ->(v) { \"#{@type}.new(\#{v})\" } emits any expression), or register a " \
+          "type the wire already parses into"
       end
     end
 
     private
 
+    # A result compares its props with eql?, so that it and #hash agree on what
+    # "same" means. A type that leaves eql? at Object's compares by identity,
+    # so two results parsed from the same bytes are unequal and useless as hash
+    # keys — whether it defined == (the common Ruby idiom, and the leaf itself
+    # then compares fine) or no equality at all. Nothing here can fix that;
+    # only the type can.
+    def warn_half_a_value_object
+      # a Module type names a duck the gem never sees an instance of; a T::Enum's
+      # values are singletons, so identity already is equality
+      return unless @klass.is_a?(Class) && !(@klass < T::Enum) && !defines?(:eql?)
+
+      GraphWeaver::Internal::Log.log(:warn) do
+        "register_scalar(#{@graphql_name.inspect}, #{@type}): #{@type} inherits #eql? and #hash, " \
+          "so its instances compare by identity — two results parsed from the same response won't " \
+          "be equal and a result won't work as a hash key — define ==, eql? and hash off the same " \
+          "values (alias_method :eql?, :== is the usual shortcut)"
+      end
+    end
+
+    def defines?(method)
+      ![BasicObject, Kernel, Object].include?(@klass.instance_method(method).owner)
+    end
+
     def coercer
+      # a cast: the registration named is the whole rule (:itself asks for
+      # no rich object, which is not the same as asking for no check)
+      return unless @cast_given.nil?
       return "id" if @graphql_name == "ID" && @type == "String"
 
       COERCERS[@type]
@@ -126,45 +231,77 @@ class GraphWeaver::Codegen
       end
     end
 
+    # Kernel's conversion functions are how a wire value becomes one of these
+    # — BigDecimal defines neither .parse nor .load, but Kernel#BigDecimal has
+    # read a decimal string all along. Only for a type the wire can't already
+    # be: Kernel#String and Kernel#Array wrap a value rather than convert it.
+    def kernel_cast
+      return unless Kernel.private_method_defined?(@type.to_sym)
+      return if WIRE_CLASSES.any? { |native| native.name == @type }
+
+      ->(type, expr) { "#{type}(#{expr})" }
+    end
+
+    # A Proc here builds SOURCE for the generated file, so a proc that
+    # converts a value (`->(v) { v.to_sym }`) can't work — it interpolates to
+    # nothing and every response fails far from the registration. Probe it
+    # once now, where the message can name the spelling.
+    def source_builder!(option, proc)
+      probe = proc.arity.zero? ? proc.call : proc.call("v")
+      return proc if probe.is_a?(String)
+
+      raise ArgumentError, "#{option}: a Proc must return the Ruby source to emit — " \
+        "e.g. #{option}: ->(v) { \"#{@type}.parse(\#{v})\" } — got #{probe.inspect}; " \
+        "a Symbol names a method instead (#{option}: :parse)"
+    rescue ArgumentError => e
+      raise if e.message.start_with?("#{option}:")
+
+      raise ArgumentError, "#{option}: a Proc takes one argument, the expression to wrap — #{e.message}"
+    end
+
     # nil infers via the matched codec; :itself opts out (identity); a
     # Symbol is a class method on the type — Money.parse(expr)
     def normalize_cast(cast, inferred)
       case cast
       when :itself then nil
       when nil then inferred && ->(expr) { inferred.call(@type, expr) }
-      when Proc then cast
+      when Proc then source_builder!(:cast, cast)
       when Symbol then ->(expr) { "#{@type}.#{cast}(#{expr})" }
       else raise ArgumentError, "cast: must be a Symbol, Proc, :itself, or nil, got #{cast.inspect}"
       end
     end
 
-    # nil infers via the matched codec; :itself opts out (identity); a
-    # Symbol is an instance method on the value — expr.to_s
+    # nil infers via the matched codec; :itself opts out (identity); a Symbol
+    # is an instance method on the value — expr.to_s — and an Array is that
+    # method with arguments: [:to_s, "F"] => expr.to_s("F")
     def normalize_serialize(serialize, inferred)
       case serialize
       when :itself then nil
       when nil then inferred && ->(expr) { inferred.call(@type, expr) }
-      when Proc then serialize
+      when Proc then source_builder!(:serialize, serialize)
       when Symbol then ->(expr) { "#{expr}.#{serialize}" }
-      else raise ArgumentError, "serialize: must be a Symbol, Proc, :itself, or nil, got #{serialize.inspect}"
+      when Array
+        method, *args = serialize
+        unless method.is_a?(Symbol)
+          # a syntax error in the generated file otherwise
+          raise ArgumentError, "serialize: an Array is [method, *arguments], got #{serialize.inspect}"
+        end
+
+        ->(expr) { "#{expr}.#{method}(#{args.map(&:inspect).join(", ")})" }
+      else raise ArgumentError, "serialize: must be a Symbol, Array, Proc, :itself, or nil, got #{serialize.inspect}"
       end
     end
 
-    # The runnable half of normalize_serialize: a Symbol names a method
-    # (:itself included, which is identity either way), an inferred codec
-    # knows its own call, and a Proc emits code there is no way to run.
+    # The runnable half of normalize_serialize: a Symbol (or Symbol with
+    # arguments) names a method — :itself included, which is identity either
+    # way — an inferred codec knows its own call, and a Proc emits code there
+    # is no way to run.
     def runtime_serialize(serialize, codec)
       case serialize
-      when Symbol then ->(value) { value.public_send(serialize) }
+      when Symbol, Array then ->(value) { value.public_send(*serialize) }
       when nil then codec && ->(value) { codec.call.call(@klass, value) }
       end
     end
-
-    # With only a type-name string we can't assume the lib is installed at
-    # codegen time, so the paths aren't loaded — only shape-checked.
-    def normalize_requires(requires)
-      GraphWeaver::Codegen.normalize_requires!(requires, load: !@klass.nil?)
-    end
   end
 
   class << self
@@ -190,7 +327,10 @@ class GraphWeaver::Codegen
         end
       end
     end
+  end
 
+  # The scalar half of one graph's registrations — see Codegen::Registry.
+  class Registry
     # Register (or override) how a GraphQL custom scalar deserializes into
     # a Ruby object and serializes back onto the wire. See ScalarType for
     # the accepted cast:/serialize:/requires: forms. Later registrations
@@ -230,36 +370,55 @@ class GraphWeaver::Codegen
       self
     end
 
-    # Built-in scalars — pre-registered entries in the one registry. Most stay
-    # pass-through: their Ruby classes (String, Integer) define neither .parse
-    # nor .load, so codec inference matches nothing and leaves them identity —
-    # which is exactly why we can name them with the real class constants.
-    # Float is the exception: JSON has one number type, so a whole Float
-    # arrives as `1` from every encoder that drops the trailing zero
-    # (graphql-js and Go both do), and Coerce.float widens that without
-    # accepting the garbage `.to_f` would silently turn into 0.0. Date
-    # deserializes via ISO-8601 (it *does* define .parse, but we want iso8601
-    # specifically, so it's explicit). The rest carry no cast and coerce
-    # input by their Ruby type — see coerce_input.
+    # Pre-registered scalars — ordinary entries in the one registry, so a
+    # later register_scalar overrides any of them.
+    #
+    # The five the spec names stay pass-through: their Ruby classes (String,
+    # Integer) define neither .parse nor .load, so inference matches nothing
+    # and leaves them identity — which is exactly why we can name them with
+    # the real class constants. Float is the exception, and its rule lives in
+    # STDLIB with the others, so `register_scalar "Ratio", Float` reads the
+    # wire exactly as the built-in Float does.
+    #
+    # The rest are names, not guesses: graphql-ruby ships all but DateTime as
+    # its own scalars, and this library runs a graphql-ruby schema in-process.
+    # DateTime is what GitHub, Shopify and most hand-written schemas call an
+    # ISO 8601 timestamp; a schema that means something else by it fails
+    # loudly (the cast raises, naming the field) and is one register_scalar
+    # away. Date and datetime are told apart by their Ruby type — a Date cast
+    # to Time would invent a midnight the server never sent.
     def register_builtin_scalars!
       register_scalar "ID", String
       register_scalar "String", String
       register_scalar "Int", Integer
-      register_scalar "Float", Float, cast: ->(expr) { "GraphWeaver::Coerce.float(#{expr})" }
+      register_scalar "Float", Float
       register_scalar "Boolean", "T::Boolean"
-      register_scalar "Date", Date, cast: :iso8601, serialize: :iso8601, requires: "date"
+      register_scalar "Date", Date
+      register_scalar "ISO8601Date", Date
+      register_scalar "ISO8601DateTime", Time
+      register_scalar "DateTime", Time
+      # graphql-ruby writes a BigInt as a string, since JSON numbers stop
+      # being exact at 2^53 — so read either spelling and write the one the
+      # server does.
+      register_scalar "BigInt", Integer,
+        cast: ->(expr) { "GraphWeaver::Coerce.integer(#{expr})" }, serialize: :to_s
+      # untyped on purpose: registering it says so, rather than leaving JSON
+      # in the "unregistered custom scalars" report every generation
+      register_scalar "JSON", "T.untyped"
+      # the objects, not the names: a later register_scalar("DateTime", ...)
+      # replaces the entry, and that is app intent rather than a pre-registration
+      @builtin_entries = scalar_registry.values.freeze
     end
     private :register_builtin_scalars!
+
+    # Whether this name still holds the entry pre-registration put there.
+    def builtin_scalar?(name)
+      entry = scalar_registry[name]
+      @builtin_entries.any? { |builtin| builtin.equal?(entry) }
+    end
   end
 
   # codegen's own record of a registration; users get one back from
   # `.scalar` but never name the class
   private_constant :ScalarType
-
-  register_builtin_scalars!
-
-  # Pre-registered rather than user intent, so generation doesn't hold a schema
-  # to them (validate_registration! skips these). Read off the registry the line
-  # above just filled: a seventh built-in shouldn't have to be named twice.
-  BUILTIN_SCALARS = scalar_registry.keys.freeze
 end