Implement schema coordinate spec as of 2025-06-06 (#4432)

This PR is applied to the `schema-coordinates` branch PR here: #3044

Implements schema coordinate spec changes per the June 5th 2025 WG discussion

graphql/graphql-spec#794

- Add support for meta-fields (e.g. `__typename`)
- Add support for introspection types
- Revert back from FieldCoordinate+ValueCoordinate -> MemberCoordinate

cc @benjie

Author: magicmark

src/language/__tests__/parser-test.ts

@@ -703,14 +703,14 @@ describe('Parser', () => {
     it('parses Name . Name', () => {
       const result = parseSchemaCoordinate('MyType.field');
       expectJSON(result).toDeepEqual({
-        kind: Kind.FIELD_COORDINATE,
+        kind: Kind.MEMBER_COORDINATE,
         loc: { start: 0, end: 12 },
         name: {
           kind: Kind.NAME,
           loc: { start: 0, end: 6 },
           value: 'MyType',
         },
-        fieldName: {
+        memberName: {
           kind: Kind.NAME,
           loc: { start: 7, end: 12 },
           value: 'field',
@@ -727,24 +727,6 @@ describe('Parser', () => {
         });
     });
 
-    it('parses Name :: Name', () => {
-      const result = parseSchemaCoordinate('MyEnum::value');
-      expectJSON(result).toDeepEqual({
-        kind: Kind.VALUE_COORDINATE,
-        loc: { start: 0, end: 13 },
-        name: {
-          kind: Kind.NAME,
-          loc: { start: 0, end: 6 },
-          value: 'MyEnum',
-        },
-        valueName: {
-          kind: Kind.NAME,
-          loc: { start: 8, end: 13 },
-          value: 'value',
-        },
-      });
-    });
-
     it('parses Name . Name ( Name : )', () => {
       const result = parseSchemaCoordinate('MyType.field(arg:)');
       expectJSON(result).toDeepEqual({

src/language/__tests__/predicates-test.ts

@@ -148,9 +148,8 @@ describe('AST node predicates', () => {
       'ArgumentCoordinate',
       'DirectiveArgumentCoordinate',
       'DirectiveCoordinate',
-      'FieldCoordinate',
+      'MemberCoordinate',
       'TypeCoordinate',
-      'ValueCoordinate',
     ]);
   });
 });

src/language/ast.ts

@@ -183,9 +183,8 @@ export type ASTNode =
   | EnumTypeExtensionNode
   | InputObjectTypeExtensionNode
   | TypeCoordinateNode
-  | FieldCoordinateNode
+  | MemberCoordinateNode
   | ArgumentCoordinateNode
-  | ValueCoordinateNode
   | DirectiveCoordinateNode
   | DirectiveArgumentCoordinateNode;
 
@@ -296,9 +295,8 @@ export const QueryDocumentKeys: {
 
   // Schema Coordinates
   TypeCoordinate: ['name'],
-  FieldCoordinate: ['name', 'fieldName'],
+  MemberCoordinate: ['name', 'memberName'],
   ArgumentCoordinate: ['name', 'fieldName', 'argumentName'],
-  ValueCoordinate: ['name', 'valueName'],
   DirectiveCoordinate: ['name'],
   DirectiveArgumentCoordinate: ['name', 'argumentName'],
 };
@@ -781,9 +779,8 @@ export interface InputObjectTypeExtensionNode {
 
 export type SchemaCoordinateNode =
   | TypeCoordinateNode
-  | FieldCoordinateNode
+  | MemberCoordinateNode
   | ArgumentCoordinateNode
-  | ValueCoordinateNode
   | DirectiveCoordinateNode
   | DirectiveArgumentCoordinateNode;
 
@@ -793,11 +790,11 @@ export interface TypeCoordinateNode {
   readonly name: NameNode;
 }
 
-export interface FieldCoordinateNode {
-  readonly kind: typeof Kind.FIELD_COORDINATE;
+export interface MemberCoordinateNode {
+  readonly kind: typeof Kind.MEMBER_COORDINATE;
   readonly loc?: Location;
   readonly name: NameNode;
-  readonly fieldName: NameNode;
+  readonly memberName: NameNode;
 }
 
 export interface ArgumentCoordinateNode {
@@ -808,13 +805,6 @@ export interface ArgumentCoordinateNode {
   readonly argumentName: NameNode;
 }
 
-export interface ValueCoordinateNode {
-  readonly kind: typeof Kind.VALUE_COORDINATE;
-  readonly loc?: Location;
-  readonly name: NameNode;
-  readonly valueName: NameNode;
-}
-
 export interface DirectiveCoordinateNode {
   readonly kind: typeof Kind.DIRECTIVE_COORDINATE;
   readonly loc?: Location;

src/language/kinds_.ts

@@ -113,15 +113,12 @@ export type INPUT_OBJECT_TYPE_EXTENSION = typeof INPUT_OBJECT_TYPE_EXTENSION;
 export const TYPE_COORDINATE = 'TypeCoordinate';
 export type TYPE_COORDINATE = typeof TYPE_COORDINATE;
 
-export const FIELD_COORDINATE = 'FieldCoordinate';
-export type FIELD_COORDINATE = typeof FIELD_COORDINATE;
+export const MEMBER_COORDINATE = 'MemberCoordinate';
+export type MEMBER_COORDINATE = typeof MEMBER_COORDINATE;
 
 export const ARGUMENT_COORDINATE = 'ArgumentCoordinate';
 export type ARGUMENT_COORDINATE = typeof ARGUMENT_COORDINATE;
 
-export const VALUE_COORDINATE = 'ValueCoordinate';
-export type VALUE_COORDINATE = typeof VALUE_COORDINATE;
-
 export const DIRECTIVE_COORDINATE = 'DirectiveCoordinate';
 export type DIRECTIVE_COORDINATE = typeof DIRECTIVE_COORDINATE;
 

src/language/lexer.ts

@@ -98,7 +98,6 @@ export function isPunctuatorTokenKind(kind: TokenKind): boolean {
     kind === TokenKind.DOT ||
     kind === TokenKind.SPREAD ||
     kind === TokenKind.COLON ||
-    kind === TokenKind.TWO_COLON ||
     kind === TokenKind.EQUALS ||
     kind === TokenKind.AT ||
     kind === TokenKind.BRACKET_L ||
@@ -272,14 +271,6 @@ function readNextToken(lexer: Lexer, start: number): Token {
         return readDot(lexer, position);
       }
       case 0x003a: // :
-        if (body.charCodeAt(position + 1) === 0x003a) {
-          return createToken(
-            lexer,
-            TokenKind.TWO_COLON,
-            position,
-            position + 2,
-          );
-        }
         return createToken(lexer, TokenKind.COLON, position, position + 1);
       case 0x003d: // =
         return createToken(lexer, TokenKind.EQUALS, position, position + 1);

src/language/parser.ts

@@ -23,7 +23,6 @@ import type {
   EnumTypeExtensionNode,
   EnumValueDefinitionNode,
   EnumValueNode,
-  FieldCoordinateNode,
   FieldDefinitionNode,
   FieldNode,
   FloatValueNode,
@@ -39,6 +38,7 @@ import type {
   IntValueNode,
   ListTypeNode,
   ListValueNode,
+  MemberCoordinateNode,
   NamedTypeNode,
   NameNode,
   NonNullTypeNode,
@@ -63,7 +63,6 @@ import type {
   TypeSystemExtensionNode,
   UnionTypeDefinitionNode,
   UnionTypeExtensionNode,
-  ValueCoordinateNode,
   ValueNode,
   VariableDefinitionNode,
   VariableNode,
@@ -1467,24 +1466,13 @@ export class Parser {
    *   - Name
    *   - Name . Name
    *   - Name . Name ( Name : )
-   *   - Name :: Name
    *   - @ Name
    *   - @ Name ( Name : )
    */
   parseSchemaCoordinate(): SchemaCoordinateNode {
     const start = this._lexer.token;
     const ofDirective = this.expectOptionalToken(TokenKind.AT);
     const name = this.parseName();
-
-    if (!ofDirective && this.expectOptionalToken(TokenKind.TWO_COLON)) {
-      const valueName = this.parseName();
-      return this.node<ValueCoordinateNode>(start, {
-        kind: Kind.VALUE_COORDINATE,
-        name,
-        valueName,
-      });
-    }
-
     let memberName: NameNode | undefined;
     if (!ofDirective && this.expectOptionalToken(TokenKind.DOT)) {
       memberName = this.parseName();
@@ -1520,10 +1508,10 @@ export class Parser {
           argumentName,
         });
       }
-      return this.node<FieldCoordinateNode>(start, {
-        kind: Kind.FIELD_COORDINATE,
+      return this.node<MemberCoordinateNode>(start, {
+        kind: Kind.MEMBER_COORDINATE,
         name,
-        fieldName: memberName,
+        memberName,
       });
     }
 

src/language/predicates.ts

@@ -117,9 +117,8 @@ export function isSchemaCoordinateNode(
 ): node is SchemaCoordinateNode {
   return (
     node.kind === Kind.TYPE_COORDINATE ||
-    node.kind === Kind.FIELD_COORDINATE ||
+    node.kind === Kind.MEMBER_COORDINATE ||
     node.kind === Kind.ARGUMENT_COORDINATE ||
-    node.kind === Kind.VALUE_COORDINATE ||
     node.kind === Kind.DIRECTIVE_COORDINATE ||
     node.kind === Kind.DIRECTIVE_ARGUMENT_COORDINATE
   );

src/language/printer.ts

@@ -325,19 +325,15 @@ const printDocASTReducer: ASTReducer<string> = {
 
   TypeCoordinate: { leave: ({ name }) => name },
 
-  FieldCoordinate: {
-    leave: ({ name, fieldName }) => join([name, wrap('.', fieldName)]),
+  MemberCoordinate: {
+    leave: ({ name, memberName }) => join([name, wrap('.', memberName)]),
   },
 
   ArgumentCoordinate: {
     leave: ({ name, fieldName, argumentName }) =>
       join([name, wrap('.', fieldName), wrap('(', argumentName, ':)')]),
   },
 
-  ValueCoordinate: {
-    leave: ({ name, valueName }) => join([name, wrap('::', valueName)]),
-  },
-
   DirectiveCoordinate: { leave: ({ name }) => join(['@', name]) },
 
   DirectiveArgumentCoordinate: {

src/language/tokenKind.ts

@@ -13,7 +13,6 @@ export const TokenKind = {
   DOT: '.' as const,
   SPREAD: '...' as const,
   COLON: ':' as const,
-  TWO_COLON: '::' as const,
   EQUALS: '=' as const,
   AT: '@' as const,
   BRACKET_L: '[' as const,

src/utilities/__tests__/resolveSchemaCoordinate-test.ts

@@ -3,6 +3,7 @@ import { describe, it } from 'mocha';
 
 import type {
   GraphQLEnumType,
+  GraphQLField,
   GraphQLInputObjectType,
   GraphQLObjectType,
 } from '../../type/definition.js';
@@ -71,16 +72,10 @@ describe('resolveSchemaCoordinate', () => {
     );
 
     expect(() => resolveSchemaCoordinate(schema, 'String.field')).to.throw(
-      'Expected "String" to be an Input Object, Object or Interface type.',
+      'Expected "String" to be an Enum, Input Object, Object or Interface type.',
     );
   });
 
-  it('does not resolve meta-fields', () => {
-    expect(
-      resolveSchemaCoordinate(schema, 'Business.__typename'),
-    ).to.deep.equal(undefined);
-  });
-
   it('resolves a Input Field', () => {
     const type = schema.getType('SearchCriteria') as GraphQLInputObjectType;
     const inputField = type.getFields().filter;
@@ -101,15 +96,15 @@ describe('resolveSchemaCoordinate', () => {
     const type = schema.getType('SearchFilter') as GraphQLEnumType;
     const enumValue = type.getValue('OPEN_NOW');
     expect(
-      resolveSchemaCoordinate(schema, 'SearchFilter::OPEN_NOW'),
+      resolveSchemaCoordinate(schema, 'SearchFilter.OPEN_NOW'),
     ).to.deep.equal({
       kind: 'EnumValue',
       type,
       enumValue,
     });
 
     expect(
-      resolveSchemaCoordinate(schema, 'SearchFilter::UNKNOWN'),
+      resolveSchemaCoordinate(schema, 'SearchFilter.UNKNOWN'),
     ).to.deep.equal(undefined);
   });
 
@@ -186,4 +181,59 @@ describe('resolveSchemaCoordinate', () => {
       'Expected "unknown" to be defined as a directive in the schema.',
     );
   });
+
+  it('resolves a meta-field', () => {
+    const type = schema.getType('Business') as GraphQLObjectType;
+    const field = schema.getField(type, '__typename');
+    expect(
+      resolveSchemaCoordinate(schema, 'Business.__typename'),
+    ).to.deep.equal({
+      kind: 'Field',
+      type,
+      field,
+    });
+  });
+
+  it('resolves a meta-field argument', () => {
+    const type = schema.getType('Query') as GraphQLObjectType;
+    const field = schema.getField(type, '__type') as GraphQLField;
+    const fieldArgument = field.args.find((arg) => arg.name === 'name');
+    expect(
+      resolveSchemaCoordinate(schema, 'Query.__type(name:)'),
+    ).to.deep.equal({
+      kind: 'FieldArgument',
+      type,
+      field,
+      fieldArgument,
+    });
+  });
+
+  it('resolves an Introspection Type', () => {
+    expect(resolveSchemaCoordinate(schema, '__Type')).to.deep.equal({
+      kind: 'NamedType',
+      type: schema.getType('__Type'),
+    });
+  });
+
+  it('resolves an Introspection Type Field', () => {
+    const type = schema.getType('__Directive') as GraphQLObjectType;
+    const field = type.getFields().name;
+    expect(resolveSchemaCoordinate(schema, '__Directive.name')).to.deep.equal({
+      kind: 'Field',
+      type,
+      field,
+    });
+  });
+
+  it('resolves an Introspection Type Enum Value', () => {
+    const type = schema.getType('__DirectiveLocation') as GraphQLEnumType;
+    const enumValue = type.getValue('INLINE_FRAGMENT');
+    expect(
+      resolveSchemaCoordinate(schema, '__DirectiveLocation.INLINE_FRAGMENT'),
+    ).to.deep.equal({
+      kind: 'EnumValue',
+      type,
+      enumValue,
+    });
+  });
 });