graph_weaver 0.1.0 → 0.2.1

data/lib/graph_weaver/codegen/emit.rb

@@ -5,10 +5,244 @@
 # Mixed into Codegen — methods run with the generator instance state.
 class GraphWeaver::Codegen
   module Emit
+    include Kernel # for sorbet: hosts are Objects
     include GraphWeaver::Inflect
 
     private
 
+    # The Relay convention — an operation whose only variable is a required
+    # input object — reads better flattened: the input's fields become
+    # execute's kwargs directly, and the wrapping level is rebuilt on the
+    # wire. Multi-variable (or nullable-input) operations keep the
+    # variable-per-kwarg surface.
+    def flatten_input(variables)
+      return unless variables.size == 1
+
+      var = variables.first
+      return unless var.required && var.node.is_a?(NonNull)
+
+      input = var.node.of
+      input if input.is_a?(InputNode)
+    end
+
+    def input_references(node)
+      node.fields.filter_map do |field|
+        child = field.node
+        child = child.of while child.respond_to?(:of)
+        child if child.is_a?(InputNode)
+      end
+    end
+
+    # Input structs in dependency order (referenced types before their
+    # referrers) so each emitted const names an already-defined class.
+    # Cycles make that impossible — flagged so emission can forward-declare
+    # every input class first, then reopen each to add its props.
+    def ordered_inputs
+      ordered = []
+      seen = {} # node => :done | :visiting (bool_exp graphs get big)
+      cyclic = T.let(false, T::Boolean)
+
+      visit = lambda do |node|
+        next if seen[node] == :done
+
+        if seen[node] == :visiting
+          cyclic = true
+          next
+        end
+
+        seen[node] = :visiting
+        input_references(node).each(&visit)
+        seen[node] = :done
+        ordered << node
+      end
+      @variable_inputs.each_value(&visit)
+
+      [ordered, cyclic]
+    end
+
+      # Mapped-enum tables, generated enums, and input structs
+      # (dependency-ordered, forward-declared when cyclic) — inline in the
+      # module that needs them, or once in the shared inputs module.
+      def emit_variable_types(out)
+          @mapped_enums.each_value do |mapped|
+            emit_mapped_enum(mapped, out, 1)
+            out << ""
+          end
+          @variable_enums.each_value do |enum|
+            emit_enum(enum, out, 1)
+            out << ""
+          end
+          inputs, cyclic = ordered_inputs
+          if cyclic
+            # Recursive input types (Hasura bool_exp et al) reference each other,
+            # so no definition order satisfies the runtime — forward-declare every
+            # class empty, then let the full definitions below reopen with props.
+            # eval'd so srb sees only the full bodies (reopening a T::Struct to
+            # add props is a static error; adding them at runtime is fine).
+            out << "  # runtime-only forward declarations: these input types reference"
+            out << "  # each other, so the full definitions below need the constants"
+            out << "  eval(<<~RUBY, binding, __FILE__, __LINE__ + 1)"
+            inputs.each { |input| out << "    class #{input.class_name} < T::Struct; end" }
+            out << "  RUBY"
+            out << ""
+          end
+          inputs.each do |input|
+            emit_input(input, out, 1)
+            out << ""
+          end
+        end
+
+      # In the shared-inputs workflow the variable types live once in the
+      # inputs module; the query module aliases what it uses, so
+      # AdoptQuery::AdoptionInput stays a real constant — and shared types
+      # keep ONE identity across every module that touches them.
+      # Only the shared names THIS module's emission references: variable
+      # root types (and, when flattened, the root input's field types)
+      # plus every mapped-enum table (result casting reads them too).
+      # Nested types stay un-aliased — they live in the inputs module.
+      def shared_alias_names(variables, flatten)
+        nodes = variables.map(&:node)
+        nodes += flatten.fields.map(&:node) if flatten
+
+        names = @mapped_enums.each_value.flat_map { |m| ["#{m.const_prefix}_FROM_WIRE", "#{m.const_prefix}_TO_WIRE"] }
+        nodes.each do |wrapped|
+          node = T.let(wrapped, T.untyped)
+          node = node.of while node.is_a?(NonNull) || node.is_a?(List)
+          case node
+          when EnumNode, InputNode then names << node.class_name
+          end
+        end
+        names.uniq
+      end
+
+      def emit_shared_aliases(out, names)
+        return if names.empty?
+
+        names.each { |name| out << "  #{name} = #{@inputs_namespace}::#{name}" }
+        out << ""
+      end
+
+      # The shared inputs artifact as files: inputs.rb (the manifest —
+      # requires, forward declarations for every struct so definition
+      # order never matters, then one require per type file) plus
+      # inputs/<type>.rb per enum/mapped-table/input struct.
+      def emit_inputs_files
+        files = {}
+        enum_files = []
+        struct_files = []
+
+        @mapped_enums.each do |graphql_name, mapped|
+          enum_files << inputs_file(files, graphql_name) { |out| emit_mapped_enum(mapped, out, 1) }
+        end
+        @variable_enums.each do |graphql_name, enum|
+          enum_files << inputs_file(files, graphql_name) { |out| emit_enum(enum, out, 1) }
+        end
+        inputs, = ordered_inputs
+        inputs.each do |input|
+          struct_files << inputs_file(files, input.class_name) { |out| emit_input(input, out, 1) }
+        end
+
+        manifest = []
+        manifest << "# typed: strict"
+        manifest << "# frozen_string_literal: true"
+        manifest << ""
+        manifest << "# Generated by GraphWeaver — do not edit. Shared variable types for"
+        manifest << "# this schema, one file per type; query modules alias what they use."
+        manifest << ""
+        requires = @requires.uniq.sort
+        if requires.any?
+          requires.each { |req| manifest << "require #{req.inspect}" }
+          manifest << ""
+        end
+        manifest << "module #{@module_name}; end"
+        manifest << ""
+        enum_files.sort.each { |file| manifest << "require_relative #{file.delete_suffix(".rb").inspect}" }
+        if inputs.any?
+          manifest << ""
+          manifest << "# runtime-only forward declarations: input types reference each"
+          manifest << "# other across files, so every constant must exist before any"
+          manifest << "# definition loads (srb sees only the full bodies)"
+          manifest << "module #{@module_name}"
+          manifest << "  eval(<<~RUBY, binding, __FILE__, __LINE__ + 1)"
+          inputs.each { |input| manifest << "    class #{input.class_name} < T::Struct; end" }
+          manifest << "  RUBY"
+          manifest << "end"
+          manifest << ""
+          struct_files.sort.each { |file| manifest << "require_relative #{file.delete_suffix(".rb").inspect}" }
+        end
+
+        files["inputs.rb"] = manifest.join("\n") + "\n"
+        files
+      end
+
+      # one type per file, wrapped in the namespace so bare sibling
+      # references resolve lexically
+      def inputs_file(files, name)
+        out = []
+        out << "# typed: strict"
+        out << "# frozen_string_literal: true"
+        out << ""
+        out << "# Generated by GraphWeaver — do not edit."
+        out << ""
+        out << "module #{@module_name}"
+        yield(out)
+        out << "end"
+
+        file = "inputs/#{GraphWeaver::Inflect.underscore(name)}.rb"
+        files[file] = out.join("\n") + "\n"
+        file
+      end
+
+    # The whole generated file: header, requires, the QUERY heredoc,
+    # enum tables, input structs (dependency-ordered, forward-declared
+    # when cyclic), the Result tree, and execute — assembled from the
+    # generator's walked state.
+    def emit_module(root, variables)
+      flatten = flatten_input(variables)
+      aliases = @inputs_namespace ? shared_alias_names(variables, flatten) : []
+
+      out = []
+      out << "# typed: strict"
+      out << "# frozen_string_literal: true"
+      out << ""
+      out << "# Generated by GraphWeaver — do not edit."
+      out << ""
+      requires = @requires.uniq.sort
+      if requires.any?
+        requires.each { |req| out << "require #{req.inspect}" }
+        out << ""
+      end
+      if aliases.any?
+        # the aliases below need the shared module loaded (same directory
+        # by the generate! convention)
+        out << "require_relative \"inputs\""
+        out << ""
+      end
+      out << "module #{@module_name}"
+      out << "  extend T::Sig"
+      out << ""
+      # a GraphQL block string could contain a bare GRAPHQL line, which
+      # would terminate the heredoc early — pick a delimiter the query
+      # can't collide with
+      delimiter = "GRAPHQL"
+      delimiter += "_" while @query.match?(/^\s*#{delimiter}\s*$/)
+      out << "  QUERY = T.let(<<~'#{delimiter}', String)"
+      @query.each_line { |line| out << "    #{line}".rstrip }
+      out << "  #{delimiter}"
+      out << ""
+      if @inputs_namespace
+        emit_shared_aliases(out, aliases)
+      else
+        emit_variable_types(out)
+      end
+      emit_nested(root, out, 1)
+      out << ""
+      emit_execute(out, variables, flatten:)
+      out << "end"
+
+      out.join("\n") + "\n"
+    end
+
     def emit_nested(node, out, indent)
       case node
       when UnionNode then emit_union(node, out, indent)
@@ -29,11 +263,30 @@ class GraphWeaver::Codegen
       out << "#{pad}end"
     end
 
+    # module-level wire translation tables for an app-mapped enum
+    def emit_mapped_enum(node, out, indent)
+      pad = "  " * indent
+      type = node.bare_type
+      prefix = node.const_prefix
+
+      out << "#{pad}# GraphQL enum #{node.graphql_name} <-> #{type} (registered mapping)"
+      out << "#{pad}#{prefix}_FROM_WIRE = T.let({"
+      node.mapping.each do |wire, member|
+        out << "#{pad}  #{wire.inspect} => #{type}.deserialize(#{member.serialize.to_s.inspect}),"
+      end
+      out << "#{pad}}.freeze, T::Hash[String, #{type}])"
+      out << "#{pad}#{prefix}_TO_WIRE = T.let(#{prefix}_FROM_WIRE.invert.freeze, T::Hash[#{type}, String])"
+    end
+
     def emit_object(node, out, indent)
       pad = "  " * indent
 
       out << "#{pad}class #{node.class_name} < T::Struct"
       out << "#{pad}  extend T::Sig"
+      out << "#{pad}  include GraphWeaver::Hints"
+      node.mixins.each do |mixin|
+        out << "#{pad}  include #{mixin} # registered for #{node.graphql_type}"
+      end
       out << ""
 
       node.fields.filter_map { |field| field.node.nested }.each do |child|
@@ -89,56 +342,74 @@ class GraphWeaver::Codegen
       out << "#{pad}end"
     end
 
-    def emit_execute(out, variables)
-      out << "  @executor = T.let(nil, T.untyped)"
+    def emit_execute(out, variables, flatten: nil)
+      out << "  @client = T.let(nil, T.untyped)"
       out << ""
       out << "  class << self"
       out << "    extend T::Sig"
       out << ""
-      out << "    sig { params(executor: T.untyped).void }"
-      out << "    attr_writer :executor"
+      out << "    sig { params(client: T.untyped).void }"
+      out << "    attr_writer :client"
       out << ""
-      out << "    # default transport for execute"
+      out << "    # default client (a GraphWeaver::Client or any transport) for"
+      out << "    # execute: per-module override, else the app default"
       out << "    sig { returns(T.untyped) }"
-      out << "    def executor"
-      out << "      @executor || #{@executor_const || "GraphWeaver.executor"}"
+      out << "    def client"
+      out << "      @client || #{@client_const || "GraphWeaver.client!"}"
       out << "    end"
       out << "  end"
       out << ""
 
-      sig_params = variables.map do |var|
-        bare = var.node.coerce? ? var.node.coerce_input_type : var.node.bare_type
-        kwarg_type = var.required ? bare : "T.nilable(#{bare})"
-        "#{var.kwarg}: #{kwarg_type}"
+      # the kwarg surface: the input's fields when flattened, else one
+      # kwarg per declared variable — typed identically either way. The
+      # per-call client override rides as an optional POSITIONAL arg, so
+      # variables keep the entire kwarg namespace (nothing is reserved).
+      params = flatten ? flatten.fields.partition(&:required).flatten : variables
+
+      sig_params = ["client: T.untyped"]
+      sig_params += params.map do |param|
+        bare = param.node.coerce? ? param.node.coerce_input_type : param.node.bare_type
+        kwarg_type = param.required || bare == "T.untyped" ? bare : "T.nilable(#{bare})"
+        "#{kwarg_name(param)}: #{kwarg_type}"
       end
-      sig_params << "executor: T.untyped"
 
-      kwargs = variables.map { |var| var.required ? "#{var.kwarg}:" : "#{var.kwarg}: nil" }
-      kwargs << "executor: self.executor"
+      kwargs = ["client = nil"]
+      kwargs += params.map { |param| param.required ? "#{kwarg_name(param)}:" : "#{kwarg_name(param)}: nil" }
 
       # execute returns the full envelope; execute! is the strict shortcut for
       # `execute(...).data!` — the typed result, or a raised QueryError.
-      forward = (variables.map { |var| "#{var.kwarg}: #{var.kwarg}" } + ["executor: executor"]).join(", ")
+      forward = (["client"] + params.map { |param| "#{kwarg_name(param)}: #{kwarg_name(param)}" }).join(", ")
 
+      if flatten
+        out << "  # $#{variables.first.wire}'s fields, flattened into kwargs (single input-object variable)"
+      end
       out << "  sig { params(#{sig_params.join(", ")}).returns(GraphWeaver::Response[Result]) }"
       out << "  def self.execute(#{kwargs.join(", ")})"
 
-      required, optional = variables.partition(&:required)
-      if required.empty?
-        out << "    variables = {}"
-      else
+      if flatten
+        fields = flatten.fields.map { |field| "#{field.prop}:" }.join(", ")
         out << "    variables = {"
-        required.each do |var|
-          out << "      #{var.wire.inspect} => #{variable_serialize(var)},"
-        end
+        out << "      #{variables.first.wire.inspect} => #{flatten.class_name}.coerce({ #{fields} }).serialize,"
         out << "    }"
-      end
-      optional.each do |var|
-        out << "    variables[#{var.wire.inspect}] = #{variable_serialize(var)} unless #{var.kwarg}.nil?"
+      else
+        required, optional = variables.partition(&:required)
+        if required.empty?
+          out << "    variables = {}"
+        else
+          out << "    variables = {"
+          required.each do |var|
+            out << "      #{var.wire.inspect} => #{variable_serialize(var)},"
+          end
+          out << "    }"
+        end
+        optional.each do |var|
+          out << "    variables[#{var.wire.inspect}] = #{variable_serialize(var)} unless #{var.kwarg}.nil?"
+        end
       end
 
       out << ""
-      out << "    raw = executor.execute(QUERY, variables: variables).to_h"
+      out << "    transport = GraphWeaver.resolve_transport(client || self.client)"
+      out << "    raw = transport.execute(QUERY, variables: variables).to_h"
       out << "    GraphWeaver::Response[Result].new("
       out << "      data: (Result.from_h(raw[\"data\"]) if raw[\"data\"]),"
       out << "      errors: (raw[\"errors\"] || []).map { |e| GraphWeaver::GraphQLError.from_h(e) },"
@@ -152,18 +423,17 @@ class GraphWeaver::Codegen
       out << "  end"
     end
 
+    # a kwarg surface entry is a VarDef (.kwarg) or, when flattened, an
+    # InputNode::Field (.prop)
+    def kwarg_name(param)
+      param.respond_to?(:kwarg) ? param.kwarg : param.prop
+    end
+
     def variable_serialize(var)
       value = var.node.coerce? ? var.node.coerce(var.kwarg) : var.kwarg
       var.node.serialize_identity? ? value : var.node.serialize(value, 1)
     end
 
-    # Structured shape for a schema-validation error: message plus its first
-    # source location, so ValidationError#errors is inspectable.
-    def validation_detail(error)
-      loc = (error.to_h["locations"]&.first if error.respond_to?(:to_h))
-      { message: error.message, line: loc && loc["line"], column: loc && loc["column"] }
-    end
-
     def field_cast(field)
       node = field.node
 
@@ -176,61 +446,30 @@ class GraphWeaver::Codegen
       end
     end
 
-    # a module-level T::Struct per input type; serialize builds the wire
-    # hash, omitting optional fields left nil
+    # A module-level T::Struct per input type: typed consts plus a FIELDS
+    # table the GraphWeaver::InputStruct runtime drives — serialize/to_h/
+    # coerce live once in the gem, not unrolled per struct (bool_exp
+    # schemas pull hundreds of inputs into one module).
     def emit_input(node, out, indent)
       pad = "  " * indent
 
       out << "#{pad}class #{node.class_name} < T::Struct"
-      out << "#{pad}  extend T::Sig"
+      out << "#{pad}  include GraphWeaver::InputStruct"
+      out << "#{pad}  extend GraphWeaver::InputStruct::ClassMethods"
       out << ""
       node.fields.each do |field|
         default = field.required ? "" : ", default: nil"
         out << "#{pad}  const :#{field.prop}, #{field.node.prop_type}#{default}"
       end
       out << ""
-      out << "#{pad}  sig { returns(T::Hash[String, T.untyped]) }"
-      out << "#{pad}  def serialize"
-      out << "#{pad}    result = T.let({}, T::Hash[String, T.untyped])"
-      node.fields.each do |field|
-        value = field.node.serialize_identity? ? field.prop.to_s : field.node.serialize(field.prop.to_s, 1)
-        line = "result[#{field.wire.inspect}] = #{value}"
-        line += " unless #{field.prop}.nil?" unless field.required
-        out << "#{pad}    #{line}"
-      end
-      out << "#{pad}    result"
-      out << "#{pad}  end"
-      out << ""
-      out << "#{pad}  # serialize, under the conventional name"
-      out << "#{pad}  sig { returns(T::Hash[String, T.untyped]) }"
-      out << "#{pad}  def to_h = serialize"
-      out << ""
-      out << "#{pad}  # Build from a plain hash (underscored keys, Symbol or String):"
-      out << "#{pad}  # enums accept their wire values, nested inputs accept hashes;"
-      out << "#{pad}  # the struct's types are enforced on construction."
-      out << "#{pad}  sig { params(value: T.any(#{node.class_name}, T::Hash[T.untyped, T.untyped])).returns(#{node.class_name}) }"
-      out << "#{pad}  def self.coerce(value)"
-      out << "#{pad}    return value if value.is_a?(#{node.class_name})"
-      out << ""
-      out << "#{pad}    new("
+      out << "#{pad}  # (prop, wire, required, serializer, coercer) per field"
+      out << "#{pad}  FIELDS = T.let(["
       node.fields.each do |field|
-        raw = "value_at(value, :#{field.prop})"
-        expr = if field.node.hash_coerce_identity?
-          raw
-        elsif field.required
-          "#{raw}.then { |v1| #{field.node.hash_coerce("v1", 2)} }"
-        else
-          "#{raw}&.then { |v1| #{field.node.hash_coerce("v1", 2)} }"
-        end
-        out << "#{pad}      #{field.prop}: #{expr},"
+        serializer = field.node.serialize_identity? ? "nil" : "->(v) { #{field.node.serialize("v", 1)} }"
+        coercer = field.node.hash_coerce_identity? ? "nil" : "->(v) { #{field.node.hash_coerce("v", 1)} }"
+        out << "#{pad}    GraphWeaver::InputStruct::Field.new(:#{field.prop}, #{field.wire.inspect}, #{field.required}, #{serializer}, #{coercer}),"
       end
-      out << "#{pad}    )"
-      out << "#{pad}  end"
-      out << ""
-      out << "#{pad}  sig { params(hash: T::Hash[T.untyped, T.untyped], key: Symbol).returns(T.untyped) }"
-      out << "#{pad}  private_class_method def self.value_at(hash, key)"
-      out << "#{pad}    hash.key?(key) ? hash[key] : hash[key.to_s]"
-      out << "#{pad}  end"
+      out << "#{pad}  ].freeze, T::Array[GraphWeaver::InputStruct::Field])"
       out << "#{pad}end"
     end
   end

data/lib/graph_weaver/codegen/enum_type.rb

@@ -0,0 +1,149 @@
+# typed: true
+# frozen_string_literal: true
+
+class GraphWeaver::Codegen
+  # How one GraphQL enum maps onto an app-owned T::Enum, so generated
+  # code speaks YOUR enum instead of generating one per module:
+  #
+  #      class PetKind < T::Enum
+  #        enums { Cat = new("cat"); Dog = new("dog") }
+  #      end
+  #
+  #      GraphWeaver.register_enum("Species", PetKind)
+  #
+  # The wire mapping is inferred by name ("CAT" <-> PetKind::Cat,
+  # case/underscore-insensitive against each member's serialized value);
+  # map: pins renames explicitly and merges over inference. Every wire
+  # value the schema declares must resolve — generation fails naming the
+  # gaps — unless fallback: names a member to absorb unknown values
+  # (forward-compat for servers that add members; inputs stay strict).
+  class EnumType
+    attr_reader :graphql_name, :type, :fallback, :requires
+
+    def initialize(graphql_name, type, map: nil, fallback: nil, requires: nil)
+      @graphql_name = graphql_name.to_s
+      unless type.is_a?(Class) && type < T::Enum
+        raise ArgumentError, "type: must be a T::Enum subclass, got #{type.inspect}"
+      end
+      unless type.name
+        raise ArgumentError, "type: must be a named constant (anonymous classes can't appear in generated source)"
+      end
+
+      @type = type
+      @map = map || {}
+      @fallback = fallback
+      @requires = Array(requires)
+
+      if fallback && !type.values.include?(fallback)
+        raise ArgumentError, "fallback: must be a #{type} member, got #{fallback.inspect}"
+      end
+    end
+
+    # wire value => member for every value the schema declares; raises
+    # naming the unmappable ones (unless fallback: absorbs them)
+    def mapping_for(wire_values)
+      mapping = {}
+      missing = []
+
+      wire_values.each do |wire|
+        member = @map[wire] || infer(wire)
+        member ? mapping[wire] = member : missing << wire
+      end
+
+      if missing.any? && !fallback
+        raise GraphWeaver::Error,
+          "#{type} has no member for #{graphql_name} value(s) #{missing.join(", ")} — " \
+          "add them, pin with map:, or absorb with fallback:"
+      end
+
+      mapping
+    end
+
+    private
+
+    # "CAT" matches serialize "cat"; "NOT_FOUND" matches "not_found"
+    def infer(wire)
+      @type.values.find { |member| normalize(member.serialize.to_s) == normalize(wire) }
+    end
+
+    def normalize(value)
+      value.downcase.delete("_")
+    end
+  end
+
+  class << self
+    # Map a GraphQL enum onto an app-owned T::Enum (see EnumType); the
+    # global default — client.register_enum scopes to one client.
+    def register_enum(graphql_name, type, map: nil, fallback: nil, requires: nil)
+      enum_registry[graphql_name.to_s] = EnumType.new(graphql_name, type, map:, fallback:, requires:)
+    end
+
+    # Bulk, inference-only form: register_enums("Species" => PetKind, ...)
+    def register_enums(mappings)
+      mappings.each { |graphql_name, type| register_enum(graphql_name, type) }
+    end
+
+    def enum_registry
+      @enum_registry ||= {}
+    end
+
+    # Attach app-owned helper modules to every struct generated from a
+    # GraphQL type — the logic stays in your code, generation wires it in:
+    #
+    #      GraphWeaver.register_type("Pet", PetHelpers)
+    #
+    # Or build the mixin inline — the block is module_eval'd into a fresh
+    # module auto-named GraphWeaver::TypeHelpers::<Type>. Handy for quick
+    # decoration; srb tc can't see into block-defined methods, so prefer
+    # a named module where static checking matters:
+    #
+    #      GraphWeaver.register_type("Pet") do
+    #        def display_name = "#{name} the pet"
+    #      end
+    #
+    # Additive: repeated registrations (and client-scoped ones) stack.
+    def register_type(graphql_name, *mixins, requires: nil, &block)
+      entry = type_registry[graphql_name.to_s] ||= { mixins: [], requires: [] }
+      add_type_helpers(entry, graphql_name, mixins, requires, block)
+    end
+
+    def type_registry
+      @type_registry ||= {}
+    end
+
+    # shared with Client#register_type: build/validate the mixins and
+    # append them to a registry entry
+    def add_type_helpers(entry, graphql_name, mixins, requires, block)
+      mixins = mixins.dup
+      mixins << helper_module(graphql_name, block) if block
+
+      raise ArgumentError, "pass one or more helper modules, or a block" if mixins.empty?
+      mixins.each do |mixin|
+        unless mixin.is_a?(Module) && mixin.name
+          raise ArgumentError, "type helpers must be named modules, got #{mixin.inspect}"
+        end
+      end
+
+      entry[:mixins].concat(mixins)
+      entry[:requires].concat(Array(requires))
+      entry
+    end
+
+    # a block-built mixin needs a name generated files can reference:
+    # GraphWeaver::TypeHelpers::Pet (suffixed on re-registration)
+    def helper_module(graphql_name, block)
+      base = GraphWeaver::Inflect.camelize(graphql_name.to_s)
+      name = base
+      count = 1
+      name = "#{base}V#{count += 1}" while GraphWeaver::TypeHelpers.const_defined?(name, false)
+      GraphWeaver::TypeHelpers.const_set(name, Module.new(&block))
+    end
+    private :helper_module
+  end
+end
+
+module GraphWeaver
+  # Home of block-built type helpers (register_type with a block), which
+  # need constant names so generated files can reference them.
+  module TypeHelpers; end
+end