Backport schema coordinates (#4493)

Author: JoviDeCroock

cspell.yml

@@ -46,6 +46,8 @@ ignoreRegExpList:
   - u\{[0-9a-f]{1,8}\}
 
 words:
+  - Coodinate
+  - metafield
   - graphiql
   - sublinks
   - instanceof

src/index.ts

@@ -215,6 +215,7 @@ export {
   parseValue,
   parseConstValue,
   parseType,
+  parseSchemaCoordinate,
   // Print
   print,
   // Visit
@@ -236,6 +237,7 @@ export {
   isTypeDefinitionNode,
   isTypeSystemExtensionNode,
   isTypeExtensionNode,
+  isSchemaCoordinateNode,
 } from './language/index';
 
 export type {
@@ -310,6 +312,13 @@ export type {
   UnionTypeExtensionNode,
   EnumTypeExtensionNode,
   InputObjectTypeExtensionNode,
+  // Schema Coordinates
+  SchemaCoordinateNode,
+  TypeCoordinateNode,
+  MemberCoordinateNode,
+  ArgumentCoordinateNode,
+  DirectiveCoordinateNode,
+  DirectiveArgumentCoordinateNode,
 } from './language/index';
 
 // Execute GraphQL queries.
@@ -460,6 +469,9 @@ export {
   DangerousChangeType,
   findBreakingChanges,
   findDangerousChanges,
+  // Schema Coordinates
+  resolveSchemaCoordinate,
+  resolveASTSchemaCoordinate,
 } from './utilities/index';
 
 export type {
@@ -489,4 +501,6 @@ export type {
   BreakingChange,
   DangerousChange,
   TypedQueryDocumentNode,
+  // Schema Coordinates
+  ResolvedSchemaElement,
 } from './utilities/index';

src/language/__tests__/parser-test.ts

@@ -8,7 +8,13 @@ import { kitchenSinkQuery } from '../../__testUtils__/kitchenSinkQuery';
 import { inspect } from '../../jsutils/inspect';
 
 import { Kind } from '../kinds';
-import { parse, parseConstValue, parseType, parseValue } from '../parser';
+import {
+  parse,
+  parseConstValue,
+  parseSchemaCoordinate,
+  parseType,
+  parseValue,
+} from '../parser';
 import { Source } from '../source';
 import { TokenKind } from '../tokenKind';
 
@@ -729,6 +735,180 @@ describe('Parser', () => {
     });
   });
 
+  describe('parseSchemaCoordinate', () => {
+    it('parses Name', () => {
+      const result = parseSchemaCoordinate('MyType');
+      expectJSON(result).toDeepEqual({
+        kind: Kind.TYPE_COORDINATE,
+        loc: { start: 0, end: 6 },
+        name: {
+          kind: Kind.NAME,
+          loc: { start: 0, end: 6 },
+          value: 'MyType',
+        },
+      });
+    });
+
+    it('parses Name . Name', () => {
+      const result = parseSchemaCoordinate('MyType.field');
+      expectJSON(result).toDeepEqual({
+        kind: Kind.MEMBER_COORDINATE,
+        loc: { start: 0, end: 12 },
+        name: {
+          kind: Kind.NAME,
+          loc: { start: 0, end: 6 },
+          value: 'MyType',
+        },
+        memberName: {
+          kind: Kind.NAME,
+          loc: { start: 7, end: 12 },
+          value: 'field',
+        },
+      });
+    });
+
+    it('rejects Name . Name . Name', () => {
+      expect(() => parseSchemaCoordinate('MyType.field.deep'))
+        .to.throw()
+        .to.deep.include({
+          message: 'Syntax Error: Expected <EOF>, found ".".',
+          locations: [{ line: 1, column: 13 }],
+        });
+    });
+
+    it('parses Name . Name ( Name : )', () => {
+      const result = parseSchemaCoordinate('MyType.field(arg:)');
+      expectJSON(result).toDeepEqual({
+        kind: Kind.ARGUMENT_COORDINATE,
+        loc: { start: 0, end: 18 },
+        name: {
+          kind: Kind.NAME,
+          loc: { start: 0, end: 6 },
+          value: 'MyType',
+        },
+        fieldName: {
+          kind: Kind.NAME,
+          loc: { start: 7, end: 12 },
+          value: 'field',
+        },
+        argumentName: {
+          kind: Kind.NAME,
+          loc: { start: 13, end: 16 },
+          value: 'arg',
+        },
+      });
+    });
+
+    it('rejects Name . Name ( Name : Name )', () => {
+      expect(() => parseSchemaCoordinate('MyType.field(arg: value)'))
+        .to.throw()
+        .to.deep.include({
+          message: 'Syntax Error: Invalid character: " ".',
+          locations: [{ line: 1, column: 18 }],
+        });
+    });
+
+    it('parses @ Name', () => {
+      const result = parseSchemaCoordinate('@myDirective');
+      expectJSON(result).toDeepEqual({
+        kind: Kind.DIRECTIVE_COORDINATE,
+        loc: { start: 0, end: 12 },
+        name: {
+          kind: Kind.NAME,
+          loc: { start: 1, end: 12 },
+          value: 'myDirective',
+        },
+      });
+    });
+
+    it('parses @ Name ( Name : )', () => {
+      const result = parseSchemaCoordinate('@myDirective(arg:)');
+      expectJSON(result).toDeepEqual({
+        kind: Kind.DIRECTIVE_ARGUMENT_COORDINATE,
+        loc: { start: 0, end: 18 },
+        name: {
+          kind: Kind.NAME,
+          loc: { start: 1, end: 12 },
+          value: 'myDirective',
+        },
+        argumentName: {
+          kind: Kind.NAME,
+          loc: { start: 13, end: 16 },
+          value: 'arg',
+        },
+      });
+    });
+
+    it('parses __Type', () => {
+      const result = parseSchemaCoordinate('__Type');
+      expectJSON(result).toDeepEqual({
+        kind: Kind.TYPE_COORDINATE,
+        loc: { start: 0, end: 6 },
+        name: {
+          kind: Kind.NAME,
+          loc: { start: 0, end: 6 },
+          value: '__Type',
+        },
+      });
+    });
+
+    it('parses Type.__metafield', () => {
+      const result = parseSchemaCoordinate('Type.__metafield');
+      expectJSON(result).toDeepEqual({
+        kind: Kind.MEMBER_COORDINATE,
+        loc: { start: 0, end: 16 },
+        name: {
+          kind: Kind.NAME,
+          loc: { start: 0, end: 4 },
+          value: 'Type',
+        },
+        memberName: {
+          kind: Kind.NAME,
+          loc: { start: 5, end: 16 },
+          value: '__metafield',
+        },
+      });
+    });
+
+    it('parses Type.__metafield(arg:)', () => {
+      const result = parseSchemaCoordinate('Type.__metafield(arg:)');
+      expectJSON(result).toDeepEqual({
+        kind: Kind.ARGUMENT_COORDINATE,
+        loc: { start: 0, end: 22 },
+        name: {
+          kind: Kind.NAME,
+          loc: { start: 0, end: 4 },
+          value: 'Type',
+        },
+        fieldName: {
+          kind: Kind.NAME,
+          loc: { start: 5, end: 16 },
+          value: '__metafield',
+        },
+        argumentName: {
+          kind: Kind.NAME,
+          loc: { start: 17, end: 20 },
+          value: 'arg',
+        },
+      });
+    });
+
+    it('rejects @ Name . Name', () => {
+      expect(() => parseSchemaCoordinate('@myDirective.field'))
+        .to.throw()
+        .to.deep.include({
+          message: 'Syntax Error: Expected <EOF>, found ".".',
+          locations: [{ line: 1, column: 13 }],
+        });
+    });
+
+    it('accepts a Source object', () => {
+      expect(parseSchemaCoordinate('MyType')).to.deep.equal(
+        parseSchemaCoordinate(new Source('MyType')),
+      );
+    });
+  });
+
   describe('operation and variable definition descriptions', () => {
     it('parses operation with description and variable descriptions', () => {
       const result = parse(dedent`

src/language/__tests__/predicates-test.ts

@@ -8,6 +8,7 @@ import {
   isConstValueNode,
   isDefinitionNode,
   isExecutableDefinitionNode,
+  isSchemaCoordinateNode,
   isSelectionNode,
   isTypeDefinitionNode,
   isTypeExtensionNode,
@@ -141,4 +142,16 @@ describe('AST node predicates', () => {
       'InputObjectTypeExtension',
     ]);
   });
+
+  it('isSchemaCoordinateNode', () => {
+    expect(
+      [
+        Kind.TYPE_COORDINATE,
+        Kind.MEMBER_COORDINATE,
+        Kind.ARGUMENT_COORDINATE,
+        Kind.DIRECTIVE_COORDINATE,
+        Kind.DIRECTIVE_ARGUMENT_COORDINATE,
+      ].every((kind) => isSchemaCoordinateNode({ kind } as ASTNode)),
+    ).to.equal(true);
+  });
 });

src/language/__tests__/printer-test.ts

@@ -5,7 +5,7 @@ import { dedent, dedentString } from '../../__testUtils__/dedent';
 import { kitchenSinkQuery } from '../../__testUtils__/kitchenSinkQuery';
 
 import { Kind } from '../kinds';
-import { parse } from '../parser';
+import { parse, parseSchemaCoordinate } from '../parser';
 import { print } from '../printer';
 
 describe('Printer: Query document', () => {
@@ -232,4 +232,33 @@ describe('Printer: Query document', () => {
     `),
     );
   });
+
+  it('prints schema coordinates', () => {
+    expect(print(parseSchemaCoordinate('Name'))).to.equal('Name');
+    expect(print(parseSchemaCoordinate('Name.field'))).to.equal('Name.field');
+    expect(print(parseSchemaCoordinate('Name.field(arg:)'))).to.equal(
+      'Name.field(arg:)',
+    );
+    expect(print(parseSchemaCoordinate('@name'))).to.equal('@name');
+    expect(print(parseSchemaCoordinate('@name(arg:)'))).to.equal('@name(arg:)');
+    expect(print(parseSchemaCoordinate('__Type'))).to.equal('__Type');
+    expect(print(parseSchemaCoordinate('Type.__metafield'))).to.equal(
+      'Type.__metafield',
+    );
+    expect(print(parseSchemaCoordinate('Type.__metafield(arg:)'))).to.equal(
+      'Type.__metafield(arg:)',
+    );
+  });
+
+  it('throws syntax error for ignored tokens in schema coordinates', () => {
+    expect(() => print(parseSchemaCoordinate('# foo\nName'))).to.throw(
+      'Syntax Error: Invalid character: "#"',
+    );
+    expect(() => print(parseSchemaCoordinate('\nName'))).to.throw(
+      'Syntax Error: Invalid character: U+000A.',
+    );
+    expect(() => print(parseSchemaCoordinate('Name .field'))).to.throw(
+      'Syntax Error: Invalid character: " "',
+    );
+  });
 });

src/language/__tests__/schemaCoordinateLexer-test.ts

@@ -0,0 +1,52 @@
+import { expect } from 'chai';
+import { describe, it } from 'mocha';
+
+import { expectToThrowJSON } from '../../__testUtils__/expectJSON';
+
+import { SchemaCoordinateLexer } from '../schemaCoordinateLexer';
+import { Source } from '../source';
+import { TokenKind } from '../tokenKind';
+
+function lexSecond(str: string) {
+  const lexer = new SchemaCoordinateLexer(new Source(str));
+  lexer.advance();
+  return lexer.advance();
+}
+
+function expectSyntaxError(text: string) {
+  return expectToThrowJSON(() => lexSecond(text));
+}
+
+describe('SchemaCoordinateLexer', () => {
+  it('can be stringified', () => {
+    const lexer = new SchemaCoordinateLexer(new Source('Name.field'));
+    expect(Object.prototype.toString.call(lexer)).to.equal(
+      '[object SchemaCoordinateLexer]',
+    );
+  });
+
+  it('tracks a schema coordinate', () => {
+    const lexer = new SchemaCoordinateLexer(new Source('Name.field'));
+    expect(lexer.advance()).to.contain({
+      kind: TokenKind.NAME,
+      start: 0,
+      end: 4,
+      value: 'Name',
+    });
+  });
+
+  it('forbids ignored tokens', () => {
+    const lexer = new SchemaCoordinateLexer(new Source('\nName.field'));
+    expectToThrowJSON(() => lexer.advance()).to.deep.equal({
+      message: 'Syntax Error: Invalid character: U+000A.',
+      locations: [{ line: 1, column: 1 }],
+    });
+  });
+
+  it('lex reports a useful syntax errors', () => {
+    expectSyntaxError('Foo .bar').to.deep.equal({
+      message: 'Syntax Error: Invalid character: " ".',
+      locations: [{ line: 1, column: 4 }],
+    });
+  });
+});