graph_weaver 0.1.0 → 0.2.0

data/lib/graph_weaver/codegen/emit.rb

@@ -29,11 +29,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 +108,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 +189,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
 
@@ -189,16 +225,26 @@ class GraphWeaver::Codegen
         out << "#{pad}  const :#{field.prop}, #{field.node.prop_type}#{default}"
       end
       out << ""
+      # locals wear the reserved __gw prefix: prop readers are bare method
+      # calls here, and a prop named "result" or "value" would otherwise
+      # be shadowed — GraphQL reserves __-names, so no field can collide
       out << "#{pad}  sig { returns(T::Hash[String, T.untyped]) }"
       out << "#{pad}  def serialize"
-      out << "#{pad}    result = T.let({}, T::Hash[String, T.untyped])"
+      out << "#{pad}    __gw_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}"
+        if field.required || field.node.serialize_identity?
+          value = field.node.serialize_identity? ? field.prop.to_s : field.node.serialize(field.prop.to_s, 1)
+          line = "__gw_result[#{field.wire.inspect}] = #{value}"
+          line += " unless #{field.prop}.nil?" unless field.required
+          out << "#{pad}    #{line}"
+        else
+          # bind a local so sorbet's flow-sensitivity narrows the nilable
+          out << "#{pad}    unless (__gw_value = #{field.prop}).nil?"
+          out << "#{pad}      __gw_result[#{field.wire.inspect}] = #{field.node.serialize("__gw_value", 1)}"
+          out << "#{pad}    end"
+        end
       end
-      out << "#{pad}    result"
+      out << "#{pad}    __gw_result"
       out << "#{pad}  end"
       out << ""
       out << "#{pad}  # serialize, under the conventional name"
@@ -212,6 +258,9 @@ class GraphWeaver::Codegen
       out << "#{pad}  def self.coerce(value)"
       out << "#{pad}    return value if value.is_a?(#{node.class_name})"
       out << ""
+      out << "#{pad}    # a typo'd key must not silently drop off the wire"
+      out << "#{pad}    GraphWeaver::Hints.validate_keys!(self, value)"
+      out << ""
       out << "#{pad}    new("
       node.fields.each do |field|
         raw = "value_at(value, :#{field.prop})"

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

data/lib/graph_weaver/codegen/nodes.rb

@@ -6,8 +6,10 @@
 # cast/serialize code to emit.
 class GraphWeaver::Codegen
   class Scalar
-    def initialize(name)
-      @scalar = GraphWeaver::Codegen.scalar(name)
+    # takes a resolved ScalarType — the generator picks it from the
+    # client-scoped overlay or the global registry
+    def initialize(scalar_type)
+      @scalar = scalar_type
     end
 
     def bare_type
@@ -15,7 +17,9 @@ class GraphWeaver::Codegen
     end
 
     def prop_type
-      "T.nilable(#{bare_type})"
+      # unregistered scalars are already T.untyped — wrapping in
+      # T.nilable is redundant and an srb tc error under typed: strict
+      bare_type == "T.untyped" ? bare_type : "T.nilable(#{bare_type})"
     end
 
     def cast(expr, _depth)
@@ -41,8 +45,13 @@ class GraphWeaver::Codegen
     def coerce(expr) = @scalar.coerce_input(expr)
     def coerce_input_type = @scalar.coerce_type
 
-    def hash_coerce(expr, _depth) = expr
-    def hash_coerce_identity? = true
+    # inside input-struct hashes, scalars coerce exactly like variable
+    # kwargs do — the registry (incl. GraphWeaver.auto_coerce) decides
+    def hash_coerce(expr, _depth)
+      @scalar.coerce_input(expr) || expr
+    end
+
+    def hash_coerce_identity? = !@scalar.coerce?
 
     def non_null? = false
     def nested = nil
@@ -71,6 +80,8 @@ class GraphWeaver::Codegen
   end
 
   class List
+    attr_reader :of
+
     def initialize(of)
       @of = of
     end
@@ -115,7 +126,7 @@ class GraphWeaver::Codegen
       inner = if @of.non_null? || @of.hash_coerce_identity?
         @of.hash_coerce_identity? ? var : @of.hash_coerce(var, depth + 1)
       else
-        "#{var}.nil? ? nil : #{@of.hash_coerce(var, depth + 1)}"
+        "#{var}&.then { |v#{depth + 1}| #{@of.hash_coerce("v#{depth + 1}", depth + 2)} }"
       end
 
       "#{expr}.map { |#{var}| #{inner} }"
@@ -130,10 +141,14 @@ class GraphWeaver::Codegen
     Field = Struct.new(:prop, :key, :node)
 
     attr_reader :class_name, :fields
+    # the GraphQL type this struct was generated from, and any registered
+    # helper modules to include (see Codegen.register_type)
+    attr_accessor :graphql_type, :mixins
 
     def initialize(class_name)
       @class_name = class_name
       @fields = []
+      @mixins = []
     end
 
     def bare_type = class_name
@@ -176,18 +191,103 @@ class GraphWeaver::Codegen
     end
 
     def serialize_identity? = false
-    def coerce? = false
 
-    # enum fields in a plain hash accept the T::Enum or its wire value
-    def hash_coerce(expr, _depth)
+    # enums always coerce: a kwarg or hash field accepts the T::Enum or
+    # its wire value (deserialize raises on anything else)
+    def coerce? = true
+
+    def coerce(expr)
       "(#{expr}.is_a?(#{class_name}) ? #{expr} : #{class_name}.deserialize(#{expr}))"
     end
 
+    def coerce_input_type = "T.any(#{class_name}, String)"
+    def hash_coerce(expr, _depth) = coerce(expr)
     def hash_coerce_identity? = false
     def non_null? = false
     def nested = self
   end
 
+  # A GraphQL enum mapped onto an app-owned T::Enum (see EnumType): no
+  # generated enum class — instead module-level <NAME>_FROM_WIRE /
+  # <NAME>_TO_WIRE constants translate at the boundary. fallback: makes
+  # casting absorb unknown wire values (inputs stay strict).
+  class MappedEnum
+    attr_reader :graphql_name, :mapping
+
+    def initialize(enum_type, wire_values)
+      @graphql_name = enum_type.graphql_name
+      @type_name = enum_type.type.name
+      @fallback = enum_type.fallback
+      @mapping = enum_type.mapping_for(wire_values)
+    end
+
+    def const_prefix = GraphWeaver::Inflect.underscore(@graphql_name).upcase
+    def fallback_const = @fallback && "#{@type_name}.deserialize(#{@fallback.serialize.to_s.inspect})"
+
+    def bare_type = @type_name
+
+    def prop_type
+      "T.nilable(#{bare_type})"
+    end
+
+    def cast(expr, _depth)
+      if @fallback
+        "#{const_prefix}_FROM_WIRE.fetch(#{expr}) { #{fallback_const} }"
+      else
+        "#{const_prefix}_FROM_WIRE.fetch(#{expr})"
+      end
+    end
+
+    def identity? = false
+
+    def serialize(expr, _depth)
+      "#{const_prefix}_TO_WIRE.fetch(#{expr})"
+    end
+
+    def serialize_identity? = false
+
+    # kwargs and hash fields accept the member or its wire value; unlike
+    # casting, bad input raises even with a fallback (a typo'd input is
+    # our bug, not server drift)
+    def coerce? = true
+
+    def coerce(expr)
+      "(#{expr}.is_a?(#{@type_name}) ? #{expr} : #{const_prefix}_FROM_WIRE.fetch(#{expr}))"
+    end
+
+    def coerce_input_type = "T.any(#{@type_name}, String)"
+    def hash_coerce(expr, _depth) = coerce(expr)
+    def hash_coerce_identity? = false
+    def non_null? = false
+    def nested = nil
+  end
+
+  # A single-condition narrowing of an abstract field (`... on Pet { ... }`
+  # and nothing else): the member struct when the runtime type matches,
+  # nil when it doesn't — a non-match's response object carries no
+  # matching fields, so the hash arrives empty. Always nilable, whatever
+  # the schema's nullability, because narrowing filters.
+  class NarrowedNode
+    def initialize(of)
+      @of = of
+    end
+
+    def class_name = @of.class_name
+    def bare_type = @of.bare_type
+
+    def prop_type
+      "T.nilable(#{bare_type})"
+    end
+
+    def cast(expr, depth)
+      "(#{expr}.empty? ? nil : #{@of.cast(expr, depth)})"
+    end
+
+    def identity? = false
+    def non_null? = false
+    def nested = @of
+  end
+
   class UnionNode
     attr_reader :class_name, :members # graphql type name => ObjectNode