RFC: Define custom scalars in terms of built-in scalars.

This proposes an additive change which allows custom scalars to be defined in terms of the built-in scalars. The motivation is for client-side code generators to understand how to map between the GraphQL type system and a native type system. As an example, a `URL` custom type may be defined in terms of the built-in scalar `String`. It could define additional serialization and parsing logic, however client tools can know to treat `URL` values as `String`. Presently, we do this by defining these mappings manually on the client, which is difficult to scale, or by giving up and making no assumptions of how the custom types serialize.

Another real use case of giving client tools this information is GraphiQL: this change will allow GraphiQL to show more useful errors when a literal of an incorrect kind is provided to a custom scalar. Currently GraphiQL simply accepts all values.

To accomplish this, this proposes adding the following:

* A new property when defining `GraphQLScalarType` (`ofType`) which asserts that only built-in scalar types are provided.

* A second type coercion to guarantee to a client that the serialized values match the `ofType`.

* Delegating the `parseLiteral` and `parseValue` functions to those in `ofType` (this enables downstream validation / GraphiQL features)

* Exposing `ofType` in the introspection system, and consuming that introspection in `buildClientSchema`.

* Adding optional syntax to the SDL, and consuming that in `buildASTSchema` and `extendSchema` as well as in `schemaPrinter`.

* Adding a case to `findBreakingChanges` which looks for a scalar's ofType changing.

Author: leebyron

src/language/__tests__/schema-kitchen-sink.graphql

@@ -75,6 +75,8 @@ scalar CustomScalar
 
 scalar AnnotatedScalar @onScalar
 
+scalar StringEncodedCustomScalar as String
+
 extend scalar CustomScalar @onScalar
 
 enum Site {

src/language/__tests__/schema-parser-test.js

@@ -754,6 +754,7 @@ type Hello {
           kind: 'ScalarTypeDefinition',
           name: nameNode('Hello', { start: 7, end: 12 }),
           description: undefined,
+          type: undefined,
           directives: [],
           loc: { start: 0, end: 12 },
         },

src/language/__tests__/schema-printer-test.js

@@ -119,6 +119,8 @@ describe('Printer: SDL document', () => {
 
       scalar AnnotatedScalar @onScalar
 
+      scalar StringEncodedCustomScalar as String
+
       extend scalar CustomScalar @onScalar
 
       enum Site {

src/language/ast.js

@@ -423,6 +423,7 @@ export type ScalarTypeDefinitionNode = {
   +loc?: Location,
   +description?: StringValueNode,
   +name: NameNode,
+  +type?: NamedTypeNode,
   +directives?: $ReadOnlyArray<DirectiveNode>,
 };
 

src/language/parser.js

@@ -864,18 +864,26 @@ function parseOperationTypeDefinition(
 }
 
 /**
- * ScalarTypeDefinition : Description? scalar Name Directives[Const]?
+ * ScalarTypeDefinition :
+ *   - Description? scalar Name ScalarOfType? Directives[Const]?
+ *
+ * ScalarOfType : as NamedType
  */
 function parseScalarTypeDefinition(lexer: Lexer<*>): ScalarTypeDefinitionNode {
   const start = lexer.token;
   const description = parseDescription(lexer);
   expectKeyword(lexer, 'scalar');
   const name = parseName(lexer);
+  let type;
+  if (skipKeyword(lexer, 'as')) {
+    type = parseNamedType(lexer);
+  }
   const directives = parseDirectives(lexer, true);
   return {
     kind: Kind.SCALAR_TYPE_DEFINITION,
     description,
     name,
+    type,
     directives,
     loc: loc(lexer, start),
   };
@@ -1512,10 +1520,24 @@ function expect(lexer: Lexer<*>, kind: TokenKindEnum): Token {
 }
 
 /**
- * If the next token is a keyword with the given value, return that token after
+ * If the next token is a keyword with the given value, return true after
  * advancing the lexer. Otherwise, do not change the parser state and return
  * false.
  */
+function skipKeyword(lexer: Lexer<*>, value: string): boolean {
+  const token = lexer.token;
+  const match = token.kind === TokenKind.NAME && token.value === value;
+  if (match) {
+    lexer.advance();
+  }
+  return match;
+}
+
+/**
+ * If the next token is a keyword with the given value, return that token after
+ * advancing the lexer. Otherwise, do not change the parser state and throw
+ * an error.
+ */
 function expectKeyword(lexer: Lexer<*>, value: string): Token {
   const token = lexer.token;
   if (token.kind === TokenKind.NAME && token.value === value) {

src/language/printer.js

@@ -113,8 +113,8 @@ const printDocASTReducer = {
 
   OperationTypeDefinition: ({ operation, type }) => operation + ': ' + type,
 
-  ScalarTypeDefinition: addDescription(({ name, directives }) =>
-    join(['scalar', name, join(directives, ' ')], ' '),
+  ScalarTypeDefinition: addDescription(({ name, type, directives }) =>
+    join(['scalar', name, wrap('as ', type), join(directives, ' ')], ' '),
   ),
 
   ObjectTypeDefinition: addDescription(

src/language/visitor.js

@@ -102,7 +102,7 @@ export const QueryDocumentKeys = {
   SchemaDefinition: ['directives', 'operationTypes'],
   OperationTypeDefinition: ['type'],
 
-  ScalarTypeDefinition: ['description', 'name', 'directives'],
+  ScalarTypeDefinition: ['description', 'name', 'type', 'directives'],
   ObjectTypeDefinition: [
     'description',
     'name',

src/type/__tests__/introspection-test.js

@@ -1355,7 +1355,9 @@ describe('Introspection', () => {
             'An enum describing what kind of type a given `__Type` is.',
           enumValues: [
             {
-              description: 'Indicates this type is a scalar.',
+              description:
+                'Indicates this type is a scalar. ' +
+                '`ofType` may represent how this scalar is serialized.',
               name: 'SCALAR',
             },
             {

src/type/definition.js

@@ -538,17 +538,26 @@ export class GraphQLScalarType {
   serialize: GraphQLScalarSerializer<*>;
   parseValue: GraphQLScalarValueParser<*>;
   parseLiteral: GraphQLScalarLiteralParser<*>;
+  ofType: ?GraphQLScalarType;
   astNode: ?ScalarTypeDefinitionNode;
   extensionASTNodes: ?$ReadOnlyArray<ScalarTypeExtensionNode>;
 
   constructor(config: GraphQLScalarTypeConfig<*, *>): void {
     this.name = config.name;
     this.description = config.description;
     this.serialize = config.serialize;
-    this.parseValue = config.parseValue || (value => value);
-    this.parseLiteral = config.parseLiteral || valueFromASTUntyped;
+    this.ofType = config.ofType || null;
+    this.parseValue =
+      config.parseValue ||
+      (this.ofType && this.ofType.parseValue) ||
+      (value => value);
+    this.parseLiteral =
+      config.parseLiteral ||
+      (this.ofType && this.ofType.parseLiteral) ||
+      valueFromASTUntyped;
     this.astNode = config.astNode;
     this.extensionASTNodes = config.extensionASTNodes;
+
     invariant(typeof config.name === 'string', 'Must provide name.');
     invariant(
       typeof config.serialize === 'function',
@@ -591,6 +600,7 @@ export type GraphQLScalarTypeConfig<TInternal, TExternal> = {|
   parseValue?: GraphQLScalarValueParser<TInternal>,
   // Parses an externally provided literal value to use as an input.
   parseLiteral?: GraphQLScalarLiteralParser<TInternal>,
+  ofType?: ?GraphQLScalarType,
   astNode?: ?ScalarTypeDefinitionNode,
   extensionASTNodes?: ?$ReadOnlyArray<ScalarTypeExtensionNode>,
 |};

src/type/introspection.js

@@ -192,8 +192,8 @@ export const __Type = new GraphQLObjectType({
     'The fundamental unit of any GraphQL Schema is the type. There are ' +
     'many kinds of types in GraphQL as represented by the `__TypeKind` enum.' +
     '\n\nDepending on the kind of a type, certain fields describe ' +
-    'information about that type. Scalar types provide no information ' +
-    'beyond a name and description, while Enum types provide their values. ' +
+    'information about that type. Scalar types provide a name, description ' +
+    'and how they serialize, while Enum types provide their possible values. ' +
     'Object and Interface types provide the fields they describe. Abstract ' +
     'types, Union and Interface, provide the Object types possible ' +
     'at runtime. List and NonNull types compose other types.',
@@ -399,7 +399,9 @@ export const __TypeKind = new GraphQLEnumType({
   values: {
     SCALAR: {
       value: TypeKind.SCALAR,
-      description: 'Indicates this type is a scalar.',
+      description:
+        'Indicates this type is a scalar. ' +
+        '`ofType` may represent how this scalar is serialized.',
     },
     OBJECT: {
       value: TypeKind.OBJECT,