graph_weaver 0.1.0 → 0.2.1

data/lib/graph_weaver/codegen/nodes.rb

@@ -1,13 +1,33 @@
 # typed: true
 # frozen_string_literal: true
 
+require "forwardable"
+
 # The typed intermediate representation of a query selection: one node
 # per GraphQL type shape, each knowing its Sorbet prop type and the
 # cast/serialize code to emit.
 class GraphWeaver::Codegen
-  class Scalar
-    def initialize(name)
-      @scalar = GraphWeaver::Codegen.scalar(name)
+  # Protocol defaults — subclasses override what differs. The full node
+  # protocol: bare_type, prop_type, cast(expr, depth), identity?,
+  # serialize(expr, depth), serialize_identity?, coerce?, coerce(expr),
+  # coerce_input_type, hash_coerce(expr, depth), hash_coerce_identity?,
+  # non_null?, nested.
+  class Node
+    def bare_type = raise(GraphWeaver::Error, "#{self.class} must define bare_type")
+    def prop_type = "T.nilable(#{bare_type})"
+    def identity? = false
+    def serialize_identity? = false
+    def coerce? = false
+    def hash_coerce_identity? = false
+    def non_null? = false
+    def nested = nil
+  end
+
+  class Scalar < Node
+    # 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 +35,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,36 +63,36 @@ 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 non_null? = false
-    def nested = nil
+    def hash_coerce_identity? = !@scalar.coerce?
   end
 
-  class NonNull
+  # NonNull is its inner node with the nilability stripped — everything
+  # else passes through.
+  class NonNull < Node
+    extend Forwardable
+
     attr_reader :of
 
+    def_delegators :@of, :bare_type, :cast, :identity?, :serialize, :serialize_identity?,
+      :coerce?, :coerce, :coerce_input_type, :hash_coerce, :hash_coerce_identity?, :nested
+
     def initialize(of)
       @of = of
     end
 
-    def bare_type = @of.bare_type
     def prop_type = bare_type
-    def cast(expr, depth) = @of.cast(expr, depth)
-    def identity? = @of.identity?
-    def serialize(expr, depth) = @of.serialize(expr, depth)
-    def serialize_identity? = @of.serialize_identity?
-    def coerce? = @of.coerce?
-    def coerce(expr) = @of.coerce(expr)
-    def coerce_input_type = @of.coerce_input_type
-    def hash_coerce(expr, depth) = @of.hash_coerce(expr, depth)
-    def hash_coerce_identity? = @of.hash_coerce_identity?
     def non_null? = true
-    def nested = @of.nested
   end
 
-  class List
+  class List < Node
+    attr_reader :of
+
     def initialize(of)
       @of = of
     end
@@ -79,10 +101,6 @@ class GraphWeaver::Codegen
       "T::Array[#{@of.prop_type}]"
     end
 
-    def prop_type
-      "T.nilable(#{bare_type})"
-    end
-
     def cast(expr, depth)
       var = "v#{depth}"
       element = if @of.non_null? || @of.identity?
@@ -108,50 +126,46 @@ class GraphWeaver::Codegen
     end
 
     def serialize_identity? = @of.serialize_identity?
-    def coerce? = false
 
     def hash_coerce(expr, depth)
       var = "v#{depth}"
       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} }"
     end
 
     def hash_coerce_identity? = @of.hash_coerce_identity?
-    def non_null? = false
     def nested = @of.nested
   end
 
-  class ObjectNode
+  class ObjectNode < Node
     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
 
-    def prop_type
-      "T.nilable(#{bare_type})"
-    end
-
     def cast(expr, _depth)
       "#{class_name}.from_h(#{expr})"
     end
 
-    def identity? = false
-    def non_null? = false
     def nested = self
   end
 
-  class EnumNode
+  class EnumNode < Node
     attr_reader :class_name, :values
 
     def initialize(class_name, values)
@@ -161,34 +175,92 @@ class GraphWeaver::Codegen
 
     def bare_type = class_name
 
-    def prop_type
-      "T.nilable(#{bare_type})"
-    end
-
     def cast(expr, _depth)
       "#{class_name}.deserialize(#{expr})"
     end
 
-    def identity? = false
-
     def serialize(expr, _depth)
       "#{expr}.serialize"
     end
 
-    def serialize_identity? = false
-    def coerce? = false
+    # enums always coerce: a kwarg or hash field accepts the T::Enum or
+    # its wire value (deserialize raises on anything else)
+    def coerce? = true
 
-    # enum fields in a plain hash accept the T::Enum or its wire value
-    def hash_coerce(expr, _depth)
+    def coerce(expr)
       "(#{expr}.is_a?(#{class_name}) ? #{expr} : #{class_name}.deserialize(#{expr}))"
     end
 
-    def hash_coerce_identity? = false
-    def non_null? = false
+    def coerce_input_type = "T.any(#{class_name}, String)"
+    def hash_coerce(expr, _depth) = coerce(expr)
     def nested = self
   end
 
-  class UnionNode
+  # 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 < Node
+    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 cast(expr, _depth)
+      if @fallback
+        "#{const_prefix}_FROM_WIRE.fetch(#{expr}) { #{fallback_const} }"
+      else
+        "#{const_prefix}_FROM_WIRE.fetch(#{expr})"
+      end
+    end
+
+    def serialize(expr, _depth)
+      "#{const_prefix}_TO_WIRE.fetch(#{expr})"
+    end
+
+    # 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)
+  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 < Node
+    def initialize(of)
+      @of = of
+    end
+
+    def class_name = @of.class_name
+    def bare_type = @of.bare_type
+
+    def cast(expr, depth)
+      "(#{expr}.empty? ? nil : #{@of.cast(expr, depth)})"
+    end
+
+    def nested = @of
+  end
+
+  class UnionNode < Node
     attr_reader :class_name, :members # graphql type name => ObjectNode
 
     def initialize(class_name, members)
@@ -198,16 +270,10 @@ class GraphWeaver::Codegen
 
     def bare_type = "#{class_name}::Type"
 
-    def prop_type
-      "T.nilable(#{bare_type})"
-    end
-
     def cast(expr, _depth)
       "#{class_name}.from_h(#{expr})"
     end
 
-    def identity? = false
-    def non_null? = false
     def nested = self
   end
 
@@ -215,7 +281,7 @@ class GraphWeaver::Codegen
   # serialize produces the wire hash. Inputs never cast FROM the wire.
   # Joins the coerce protocol so execute kwargs accept plain hashes,
   # normalized (and type-checked) through the generated .coerce.
-  class InputNode
+  class InputNode < Node
     Field = Struct.new(:prop, :wire, :node, :required)
 
     attr_reader :class_name, :fields
@@ -227,18 +293,12 @@ class GraphWeaver::Codegen
 
     def bare_type = class_name
 
-    def prop_type
-      "T.nilable(#{bare_type})"
-    end
-
     def serialize(expr, _depth)
       "#{expr}.serialize"
     end
 
-    def serialize_identity? = false
-
     def cast(_expr, _depth)
-      raise NotImplementedError, "input objects are never cast from responses"
+      raise GraphWeaver::Error, "input objects are never cast from responses"
     end
 
     def coerce? = true
@@ -247,10 +307,5 @@ class GraphWeaver::Codegen
 
     # building a struct field from a caller-supplied plain hash value
     def hash_coerce(expr, _depth) = "#{class_name}.coerce(#{expr})"
-    def hash_coerce_identity? = false
-
-    def identity? = false
-    def non_null? = false
-    def nested = nil
   end
 end

data/lib/graph_weaver/codegen/scalar_type.rb

@@ -1,6 +1,8 @@
 # typed: true
 # frozen_string_literal: true
 
+require "date"
+
 class GraphWeaver::Codegen
 
   # How one GraphQL scalar maps to Ruby: the Sorbet prop type, the
@@ -15,17 +17,17 @@ class GraphWeaver::Codegen
   # 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:
-  #   type: Money   (defines .parse)   => Money.parse(expr) / expr.to_s
-  #   type: Blob    (defines .load)    => Blob.load(expr)   / Blob.dump(expr)
+  #      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,
   # so inferring a serializer off it would wrongly wrap plain types (String,
   # Integer) — pairing off a deserializer the type actually defines avoids
   # that. Override with an explicit value:
   #   - 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)
+  #           cast: :load        => "Blob.load(expr)"    (class method on type)
+  #           serialize: :to_json => "expr.to_json"      (instance method)
   #   - a Proc handles anything a Symbol can't express:
-  #       cast: ->(e) { "Money.new(#{e})" }
+  #           cast: ->(e) { "Money.new(#{e})" }
   #   - :itself opts out — force identity pass-through even when a codec
   #     would otherwise match (rare)
   # requires: a String or Array of paths emitted as `require`s atop the
@@ -56,23 +58,44 @@ class GraphWeaver::Codegen
 
     attr_reader :graphql_name, :type, :requires
 
-    def initialize(graphql_name, type:, cast: nil, serialize: nil, requires: nil, coerce: false)
+    def initialize(graphql_name, type, cast: nil, serialize: nil, requires: nil, coerce: nil)
       @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)
       codec = @klass && CODECS.find { |c| @klass.respond_to?(c.probe) }
       @cast = normalize_cast(cast, codec&.cast)
       @serialize = normalize_serialize(serialize, codec&.serialize)
-      @requires = normalize_requires(requires)
       @coerce = coerce
       validate_coerce!
     end
 
+    # conversions applied to the four convertible built-ins when the
+    # global GraphWeaver.auto_coerce is on and no explicit coerce: given
+    AUTO_CONVERSIONS = {
+      "ID" => :to_s, "String" => :to_s, "Int" => :to_i, "Float" => :to_f,
+    }.freeze
+
     def cast(expr) = @cast&.call(expr)
     def cast? = !@cast.nil?
     def serialize(expr) = @serialize&.call(expr)
     def serialize? = !@serialize.nil?
-    def coerce? = !!@coerce
+    def coerce? = !!effective_coerce
+
+    # Explicit coerce: always wins (false means never). Left unset, the
+    # global GraphWeaver.auto_coerce decides — resolved HERE, at
+    # generation time, so registration order doesn't matter: convertible
+    # built-ins get their conversion, anything with a full cast/serialize
+    # pair gets parse-style coercion.
+    def effective_coerce
+      return @coerce unless @coerce.nil?
+      return false unless GraphWeaver.auto_coerce
+
+      AUTO_CONVERSIONS.fetch(@graphql_name) { (cast? && serialize?) || nil }
+    end
 
     # The code that normalizes a variable input before it's serialized. Two
     # shapes: coerce: true parses a raw value into the rich type via the cast
@@ -82,17 +105,17 @@ class GraphWeaver::Codegen
     # afterward, but is identity for the conversion built-ins, so the
     # converted value goes on the wire natively (a Float, not "5.0").
     def coerce_input(expr)
-      case @coerce
+      case effective_coerce
       when true then "(#{expr}.is_a?(#{@type}) ? #{expr} : #{cast(expr)})"
-      when Symbol then "#{expr}.#{@coerce}"
+      when Symbol then "#{expr}.#{effective_coerce}"
       end
     end
 
     # the accepted Sorbet type for a coercible variable kwarg
     def coerce_type
-      case @coerce
+      case effective_coerce
       when true then "T.any(#{@type}, String)"
-      when Symbol then CONVERT_INPUTS.fetch(@coerce, "T.untyped")
+      when Symbol then CONVERT_INPUTS.fetch(effective_coerce, "T.untyped")
       end
     end
 
@@ -175,9 +198,9 @@ class GraphWeaver::Codegen
     # the accepted cast:/serialize:/requires: forms. Later registrations
     # win, so an app can override a built-in (e.g. map Date onto its own
     # type).
-    def register_scalar(graphql_name, type:, cast: nil, serialize: nil, requires: nil, coerce: false)
+    def register_scalar(graphql_name, type, cast: nil, serialize: nil, requires: nil, coerce: nil)
       scalar_registry[graphql_name.to_s] =
-        ScalarType.new(graphql_name, type:, cast:, serialize:, requires:, coerce:)
+        ScalarType.new(graphql_name, type, cast:, serialize:, requires:, coerce:)
     end
 
     # The ScalarType for a scalar name; unknown scalars fall back to an
@@ -185,7 +208,7 @@ class GraphWeaver::Codegen
     # scalars outside the table.
     def scalar(graphql_name)
       scalar_registry.fetch(graphql_name.to_s) do
-        ScalarType.new(graphql_name, type: "T.untyped")
+        ScalarType.new(graphql_name, "T.untyped")
       end
     end
 
@@ -201,14 +224,12 @@ class GraphWeaver::Codegen
     end
 
     # Drop every custom registration and restore the built-in scalars — the
-    # clean slate to reach for between tests, or to undo overrides. Pass
-    # coerce: true to reload the built-ins with input coercion enabled
-    # (Float accepts 5/"5" and .to_f's it, etc.), then register your own
-    # scalars on top — a one-liner alternative to re-registering each
-    # built-in by hand.
-    def reset_scalars!(coerce: false)
+    # clean slate to reach for between tests, or to undo overrides. (Want
+    # the built-ins to coerce loose input? That's GraphWeaver.auto_coerce,
+    # resolved at generation time — no re-registering.)
+    def reset_scalars!
       clear_scalars!
-      register_builtin_scalars!(coerce:)
+      register_builtin_scalars!
       self
     end
 
@@ -218,19 +239,16 @@ class GraphWeaver::Codegen
     # matches nothing and leaves them identity — which is exactly why we
     # can name them with the real class constants. Date deserializes via
     # ISO-8601 (it *does* define .parse, but we want iso8601 specifically,
-    # so it's explicit).
-    #
-    # coerce: true opts the convertible scalars into input coercion via a
-    # plain conversion method (to_f/to_i/to_s); the wire value stays native
-    # (a Float, not "5.0"). Boolean and Date have no lossless one-method
-    # conversion, so they stay strict either way.
-    def register_builtin_scalars!(coerce: false)
-      register_scalar "ID", type: String, coerce: (:to_s if coerce)
-      register_scalar "String", type: String, coerce: (:to_s if coerce)
-      register_scalar "Int", type: Integer, coerce: (:to_i if coerce)
-      register_scalar "Float", type: Float, coerce: (:to_f if coerce)
-      register_scalar "Boolean", type: "T::Boolean"
-      register_scalar "Date", type: Date, cast: :iso8601, serialize: :iso8601, requires: "date"
+    # so it's explicit). Input coercion is a generation-time concern:
+    # GraphWeaver.auto_coerce gives the convertible built-ins their
+    # conversion (see ScalarType::AUTO_CONVERSIONS).
+    def register_builtin_scalars!
+      register_scalar "ID", String
+      register_scalar "String", String
+      register_scalar "Int", Integer
+      register_scalar "Float", Float
+      register_scalar "Boolean", "T::Boolean"
+      register_scalar "Date", Date, cast: :iso8601, serialize: :iso8601, requires: "date"
     end
   end