graph_weaver 0.5.1 → 0.6.1

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
@@ -34,85 +37,117 @@ class GraphWeaver::Codegen
   class ScalarType
     # Inferred (deserialize, serialize) codecs, tried in order; the first
     # whose probe the Ruby type defines as a class method wins, and its
-    # serialize is paired with it. Builders take (type_name, expr) => code.
-    Codec = Struct.new(:probe, :cast, :serialize)
+    # serialize is paired with it. Builders take (type_name, expr) => code;
+    # `call` is the same serialization run rather than emitted, for the
+    # testing harness (see #serialize_value).
+    Codec = Struct.new(:probe, :cast, :serialize, :call)
     CODECS = [
       Codec.new(:parse, # Type.parse(wire) <-> value.to_s
         ->(type, expr) { "#{type}.parse(#{expr})" },
-        ->(_type, expr) { "#{expr}.to_s" }),
+        ->(_type, expr) { "#{expr}.to_s" },
+        ->(_klass, value) { value.to_s }),
       Codec.new(:load, # Type.load(wire) <-> Type.dump(value)
         ->(type, expr) { "#{type}.load(#{expr})" },
-        ->(type, expr) { "#{type}.dump(#{expr})" }),
+        ->(type, expr) { "#{type}.dump(#{expr})" },
+        ->(klass, value) { klass.dump(value) }),
     ].freeze
 
-    # How a built-in converts a loose variable input, and the widened kwarg
-    # it then accepts. Only the numerics can: a String/ID/Boolean input is
-    # already its own Ruby type, so there is nothing to convert.
-    Conversion = Struct.new(:via, :input_type)
-    CONVERSIONS = {
-      "Int" => Conversion.new(:to_i, "T.any(Integer, Float, String)"),
-      "Float" => Conversion.new(:to_f, "T.any(Float, Integer, String)"),
+    # 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.
+    COERCERS = {
+      "Integer" => "integer",
+      "Float" => "float",
+      "String" => "string",
+      "T::Boolean" => "boolean",
     }.freeze
 
+    # 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.
+    STDLIB = {
+      "BigDecimal" => { serialize: [:to_s, "F"], requires: "bigdecimal" },
+      "Date" => { cast: :iso8601, serialize: :iso8601, requires: "date" },
+      "Time" => { cast: :parse, serialize: :iso8601, requires: "time" },
+      "DateTime" => { cast: :iso8601, serialize: :iso8601, 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
 
-    def initialize(graphql_name, type, cast: nil, serialize: nil, requires: nil, coerce: nil)
+    def initialize(graphql_name, type, cast: nil, serialize: nil, requires: 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)
+      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
       codec = @klass && CODECS.find { |c| @klass.respond_to?(c.probe) }
-      @cast = normalize_cast(cast, codec&.cast)
-      @serialize = normalize_serialize(serialize, codec&.serialize)
-      @coerce = coerce
-      validate_coerce!
+      @cast = normalize_cast(cast || known[:cast], codec&.cast || kernel_cast)
+      @serialize = normalize_serialize(serialize || known[:serialize], codec&.serialize)
+      @serialize_value = runtime_serialize(serialize || known[:serialize], codec)
     end
 
     def cast(expr) = @cast&.call(expr)
     def cast? = !@cast.nil?
     def serialize(expr) = @serialize&.call(expr)
     def serialize? = !@serialize.nil?
-    def coerce? = !!coercion
-
-    # How this scalar coerces a variable input, or nil for not at all.
-    # coerce: says WHETHER (explicit always wins); left unset the global
-    # GraphWeaver.auto_coerce decides — resolved HERE, at generation time,
-    # so registration order doesn't matter. The scalar itself says HOW: a
-    # convertible built-in converts, anything with a full cast/serialize
-    # pair parses. Nothing left to try means it can't coerce.
-    def coercion
-      return if @coerce == false
-      return if @coerce.nil? && !GraphWeaver.auto_coerce
-
-      CONVERSIONS[@graphql_name] || (:parse if cast? && serialize?)
-    end
+    def coerce? = !coerce_input("v").nil?
 
-    # The code that normalizes a variable input before it's serialized.
-    # Parsing runs a raw value through the cast, guarded so an already-typed
-    # value passes through; a conversion just calls the method (5, "5" ->
-    # 5.0). serialize still runs afterward, but is identity for the
-    # convertible built-ins, so the converted value goes on the wire
-    # natively (a Float, not "5.0").
-    def coerce_input(expr)
-      case (how = coercion)
-      when :parse then "(#{expr}.is_a?(#{@type}) ? #{expr} : #{cast(expr)})"
-      when Conversion then "#{expr}.#{how.via}"
-      end
+    # #serialize run rather than emitted: the wire value for a Ruby one. The
+    # testing harness reads app objects — a Time, a Money — off an object pin
+    # and has to write what the server would. A `serialize:` proc builds code
+    # and can't be run, so its value passes through and the cast complains.
+    def serialize_value(value)
+      return value if value.nil? || @serialize_value.nil?
+
+      @serialize_value.call(value)
     end
 
-    # the accepted Sorbet type for a coercible variable kwarg
-    def coerce_type
-      case (how = coercion)
-      when :parse then "T.any(#{@type}, String)"
-      when Conversion then how.input_type
+    # 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.
+    def coerce_input(expr)
+      if cast?
+        "(#{expr}.is_a?(#{@type}) ? #{expr} : #{cast(expr)})"
+      elsif (fn = coercer)
+        "GraphWeaver::Coerce.#{fn}(#{expr})"
       end
     end
 
     private
 
+    def coercer
+      return "id" if @graphql_name == "ID" && @type == "String"
+
+      COERCERS[@type]
+    end
+
     def type_name(type)
       case type
       when Module
@@ -124,6 +159,17 @@ 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
+
     # 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)
@@ -136,37 +182,35 @@ class GraphWeaver::Codegen
       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 Symbol then ->(expr) { "#{expr}.#{serialize}" }
-      else raise ArgumentError, "serialize: must be a Symbol, Proc, :itself, or nil, got #{serialize.inspect}"
-      end
-    end
+      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
 
-    # 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?)
+        ->(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
 
-    # coerce: true asks for something the scalar has to know how to do, so
-    # refuse a pass-through one now rather than emit a silent no-op.
-    def validate_coerce!
-      case @coerce
-      when false, nil then nil
-      when true
-        return if coercion
-
-        raise ArgumentError,
-          "coerce: true needs a cast and a serialize (#{@graphql_name} has neither, " \
-          "so there is nothing to coerce)"
-      else
-        raise ArgumentError, "coerce: must be true or false, got #{@coerce.inspect}"
+    # 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, Array then ->(value) { value.public_send(*serialize) }
+      when nil then codec && ->(value) { codec.call.call(@klass, value) }
       end
     end
   end
@@ -200,18 +244,19 @@ 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: nil)
+    def register_scalar(graphql_name, type, cast: nil, serialize: nil, requires: nil)
       scalar_registry[graphql_name.to_s] =
-        ScalarType.new(graphql_name, type, cast:, serialize:, requires:, coerce:)
+        ScalarType.new(graphql_name, type, cast:, serialize:, requires:)
     end
 
-    # The ScalarType for a scalar name; unknown scalars fall back to an
-    # untyped pass-through (T.untyped, no cast) — the prior behavior for
-    # scalars outside the table.
-    def scalar(graphql_name)
-      scalar_registry.fetch(graphql_name.to_s) do
-        ScalarType.new(graphql_name, "T.untyped")
-      end
+    # The ScalarType in play for a scalar, most specific first: the
+    # `Type.field` registration when `coordinate` names one, then the
+    # scalar-name registration. Unknown scalars fall back to an untyped
+    # pass-through (T.untyped, no cast) — the prior behavior for scalars
+    # outside the table.
+    def scalar(graphql_name, coordinate = nil)
+      (coordinate && scalar_registry[coordinate.to_s]) ||
+        scalar_registry.fetch(graphql_name.to_s) { ScalarType.new(graphql_name, "T.untyped") }
     end
 
     def scalar_registry
@@ -226,33 +271,57 @@ 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. (Want
-    # the built-ins to coerce loose input? That's GraphWeaver.auto_coerce,
-    # resolved at generation time — no re-registering.)
+    # clean slate to reach for between tests, or to undo overrides.
     def reset_scalars!
       clear_scalars!
       register_builtin_scalars!
       self
     end
 
-    # Built-in scalars — pre-registered entries in the one registry. The
-    # standard scalars stay pass-through: their Ruby classes (String,
-    # Integer, Float) 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. Date deserializes via
-    # ISO-8601 (it *does* define .parse, but we want iso8601 specifically,
-    # so it's explicit). Whether a variable of one accepts loose input is a
-    # separate, generation-time question — see coercion.
+    # 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: 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.
+    #
+    # 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
+      register_scalar "Float", Float, cast: ->(expr) { "GraphWeaver::Coerce.float(#{expr})" }
       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"
     end
+    private :register_builtin_scalars!
   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

data/lib/graph_weaver/codegen/type_helpers.rb

@@ -82,6 +82,7 @@ class GraphWeaver::Codegen
     # arbitrary text that could inject code
     ALIAS_NAME = /\A[a-zA-Z_]\w*[?!]?\z/
     ALIAS_SEGMENT = /\A[a-zA-Z_]\w*\z/
+    private_constant :ALIAS_NAME, :ALIAS_SEGMENT
 
     # { accessor => { segments:, optional: } } from a path string (accessor
     # named after the last segment), an array of such, or an { accessor => path }