graph_weaver 0.6.1 → 0.7.1

data/lib/graph_weaver/codegen/scalar_type.rb

@@ -52,15 +52,17 @@ 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
 
     # What the library already knows about a Ruby type, so registering one
@@ -72,11 +74,25 @@ class GraphWeaver::Codegen
     #     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" },
-      "Date" => { cast: :iso8601, serialize: :iso8601, requires: "date" },
-      "Time" => { cast: :parse, serialize: :iso8601, requires: "time" },
-      "DateTime" => { cast: :iso8601, serialize: :iso8601, requires: "date" },
+      # 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
@@ -104,10 +120,13 @@ class GraphWeaver::Codegen
         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 || known[:cast], codec&.cast || kernel_cast)
       @serialize = normalize_serialize(serialize || known[:serialize], codec&.serialize)
-      @serialize_value = runtime_serialize(serialize || known[:serialize], codec)
+      @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)
@@ -128,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]
@@ -170,13 +242,30 @@ class GraphWeaver::Codegen
       ->(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
@@ -189,7 +278,7 @@ class GraphWeaver::Codegen
       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}" }
       when Array
         method, *args = serialize
@@ -238,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
@@ -284,10 +376,9 @@ class GraphWeaver::Codegen
     # 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 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.
@@ -300,7 +391,7 @@ class GraphWeaver::Codegen
       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
       register_scalar "ISO8601Date", Date
@@ -314,18 +405,20 @@ class GraphWeaver::Codegen
       # 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

data/lib/graph_weaver/codegen/type_helpers.rb

@@ -11,16 +11,18 @@
 # path is resolved against an actual selection).
 
 class GraphWeaver::Codegen
-  class << self
+  # The extend_type half of one graph's registrations — see Codegen::Registry.
+  class Registry
     # Attach app-owned helper modules to every struct generated from a
     # GraphQL type — the logic stays in your code, generation wires it in:
     #
     #      GraphWeaver.extend_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:
+    # module named for where it is written and what it extends:
+    # GraphWeaver::TypeHelpers::Pet, or ::Billing::Pet in graph :billing.
+    # Handy for quick decoration; srb tc can't see into block-defined methods,
+    # so prefer a named module where static checking matters:
     #
     #      GraphWeaver.extend_type("Pet") do
     #        def display_name = "#{name} the pet"
@@ -118,19 +120,62 @@ class GraphWeaver::Codegen
     # generated files may still name them.
     def reset_type_helpers!
       type_registry.clear
+      helper_counts.clear
       self
     end
 
-    # a block-built mixin needs a name generated files can reference:
-    # GraphWeaver::TypeHelpers::Pet (suffixed on re-registration)
+    # Which graph's registrations this registry holds — nil for the top-level
+    # one. Block-built helpers are named for it, so two graphs extending the
+    # same type get two constants (see helper_module).
+    attr_accessor :graph_name
+
+    # A block-built mixin needs a name generated files can reference:
+    # GraphWeaver::TypeHelpers::Pet, or ::Billing::Pet in graph :billing (V2,
+    # V3… for a second and third block on the same type in the same place).
+    #
+    # The name is a function of the source and nothing else — where the block
+    # is written and what it extends. It gets baked into generated code, so
+    # naming it after whichever constants happened to exist made it a function
+    # of how many times THIS process had read the registry, and `generate`
+    # wrote a name a plain boot never creates.
     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))
+      namespace = helper_namespace
+      type = GraphWeaver::Inflect.camelize(graphql_name.to_s)
+      index = (helper_counts[[namespace.name, type]] += 1)
+      name = index == 1 ? type : "#{type}V#{index}"
+      # reused rather than replaced, so re-declaring the same source (a Rails
+      # to_prepare reload) keeps the module already-loaded structs include
+      mod = const_under(namespace, name) { Module.new }
+      mod.module_eval(&block)
+      mod
     end
     private :helper_module
+
+    # Where this registry's block-built helpers live: under a module named for
+    # the graph, so two graphs extending the same type get two constants and
+    # neither has to know the other exists.
+    def helper_namespace
+      return GraphWeaver::TypeHelpers unless graph_name
+
+      const_under(GraphWeaver::TypeHelpers, GraphWeaver::Inflect.camelize(graph_name.to_s)) { Module.new }
+    end
+    private :helper_namespace
+
+    def const_under(namespace, name)
+      return namespace.const_get(name, false) if namespace.const_defined?(name, false)
+
+      namespace.const_set(name, yield)
+    end
+    private :const_under
+
+    # How many block-built helpers this registry has already named for a type.
+    # Per registry, not per process: a graph's registrations are replayed over
+    # a fresh copy of the top-level registry on every read, so the same source
+    # counts the same way every time.
+    def helper_counts
+      @helper_counts ||= Hash.new(0)
+    end
+    private :helper_counts
   end
 end