graphql 16.11.0 → 16.13.0

package/language/parser.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, '__esModule', {
 exports.Parser = void 0;
 exports.parse = parse;
 exports.parseConstValue = parseConstValue;
+exports.parseSchemaCoordinate = parseSchemaCoordinate;
 exports.parseType = parseType;
 exports.parseValue = parseValue;
 
@@ -19,6 +20,8 @@ var _kinds = require('./kinds.js');
 
 var _lexer = require('./lexer.js');
 
+var _schemaCoordinateLexer = require('./schemaCoordinateLexer.js');
+
 var _source = require('./source.js');
 
 var _tokenKind = require('./tokenKind.js');
@@ -84,6 +87,29 @@ function parseType(source, options) {
   parser.expectToken(_tokenKind.TokenKind.EOF);
   return type;
 }
+/**
+ * Given a string containing a GraphQL Schema Coordinate (ex. `Type.field`),
+ * parse the AST for that schema coordinate.
+ * Throws GraphQLError if a syntax error is encountered.
+ *
+ * Consider providing the results to the utility function:
+ * resolveASTSchemaCoordinate(). Or calling resolveSchemaCoordinate() directly
+ * with an unparsed source.
+ */
+
+function parseSchemaCoordinate(source) {
+  const sourceObj = (0, _source.isSource)(source)
+    ? source
+    : new _source.Source(source);
+  const lexer = new _schemaCoordinateLexer.SchemaCoordinateLexer(sourceObj);
+  const parser = new Parser(source, {
+    lexer,
+  });
+  parser.expectToken(_tokenKind.TokenKind.SOF);
+  const coordinate = parser.parseSchemaCoordinate();
+  parser.expectToken(_tokenKind.TokenKind.EOF);
+  return coordinate;
+}
 /**
  * This class is exported only to assist people in implementing their own parsers
  * without duplicating too much code and should be used only as last resort for cases
@@ -98,11 +124,18 @@ function parseType(source, options) {
 
 class Parser {
   constructor(source, options = {}) {
-    const sourceObj = (0, _source.isSource)(source)
-      ? source
-      : new _source.Source(source);
-    this._lexer = new _lexer.Lexer(sourceObj);
-    this._options = options;
+    const { lexer, ..._options } = options;
+
+    if (lexer) {
+      this._lexer = lexer;
+    } else {
+      const sourceObj = (0, _source.isSource)(source)
+        ? source
+        : new _source.Source(source);
+      this._lexer = new _lexer.Lexer(sourceObj);
+    }
+
+    this._options = _options;
     this._tokenCounter = 0;
   }
 
@@ -169,6 +202,14 @@ class Parser {
       ? this._lexer.lookahead()
       : this._lexer.token;
 
+    if (hasDescription && keywordToken.kind === _tokenKind.TokenKind.BRACE_L) {
+      throw (0, _syntaxError.syntaxError)(
+        this._lexer.source,
+        this._lexer.token.start,
+        'Unexpected description, descriptions are not supported on shorthand queries.',
+      );
+    }
+
     if (keywordToken.kind === _tokenKind.TokenKind.NAME) {
       switch (keywordToken.value) {
         case 'schema':
@@ -196,14 +237,6 @@ class Parser {
           return this.parseDirectiveDefinition();
       }
 
-      if (hasDescription) {
-        throw (0, _syntaxError.syntaxError)(
-          this._lexer.source,
-          this._lexer.token.start,
-          'Unexpected description, descriptions are supported only on type definitions.',
-        );
-      }
-
       switch (keywordToken.value) {
         case 'query':
         case 'mutation':
@@ -212,7 +245,17 @@ class Parser {
 
         case 'fragment':
           return this.parseFragmentDefinition();
+      }
+
+      if (hasDescription) {
+        throw (0, _syntaxError.syntaxError)(
+          this._lexer.source,
+          this._lexer.token.start,
+          'Unexpected description, only GraphQL definitions support descriptions.',
+        );
+      }
 
+      switch (keywordToken.value) {
         case 'extend':
           return this.parseTypeSystemExtension();
       }
@@ -234,6 +277,7 @@ class Parser {
       return this.node(start, {
         kind: _kinds.Kind.OPERATION_DEFINITION,
         operation: _ast.OperationTypeNode.QUERY,
+        description: undefined,
         name: undefined,
         variableDefinitions: [],
         directives: [],
@@ -241,6 +285,7 @@ class Parser {
       });
     }
 
+    const description = this.parseDescription();
     const operation = this.parseOperationType();
     let name;
 
@@ -251,6 +296,7 @@ class Parser {
     return this.node(start, {
       kind: _kinds.Kind.OPERATION_DEFINITION,
       operation,
+      description,
       name,
       variableDefinitions: this.parseVariableDefinitions(),
       directives: this.parseDirectives(false),
@@ -295,6 +341,7 @@ class Parser {
   parseVariableDefinition() {
     return this.node(this._lexer.token, {
       kind: _kinds.Kind.VARIABLE_DEFINITION,
+      description: this.parseDescription(),
       variable: this.parseVariable(),
       type:
         (this.expectToken(_tokenKind.TokenKind.COLON),
@@ -443,6 +490,7 @@ class Parser {
 
   parseFragmentDefinition() {
     const start = this._lexer.token;
+    const description = this.parseDescription();
     this.expectKeyword('fragment'); // Legacy support for defining variables within fragments changes
     // the grammar of FragmentDefinition:
     //   - fragment FragmentName VariableDefinitions? on TypeCondition Directives? SelectionSet
@@ -450,6 +498,7 @@ class Parser {
     if (this._options.allowLegacyFragmentVariables === true) {
       return this.node(start, {
         kind: _kinds.Kind.FRAGMENT_DEFINITION,
+        description,
         name: this.parseFragmentName(),
         variableDefinitions: this.parseVariableDefinitions(),
         typeCondition: (this.expectKeyword('on'), this.parseNamedType()),
@@ -460,6 +509,7 @@ class Parser {
 
     return this.node(start, {
       kind: _kinds.Kind.FRAGMENT_DEFINITION,
+      description,
       name: this.parseFragmentName(),
       typeCondition: (this.expectKeyword('on'), this.parseNamedType()),
       directives: this.parseDirectives(false),
@@ -1364,6 +1414,72 @@ class Parser {
     }
 
     throw this.unexpected(start);
+  } // Schema Coordinates
+
+  /**
+   * SchemaCoordinate :
+   *   - Name
+   *   - Name . Name
+   *   - Name . Name ( Name : )
+   *   - \@ Name
+   *   - \@ Name ( Name : )
+   */
+
+  parseSchemaCoordinate() {
+    const start = this._lexer.token;
+    const ofDirective = this.expectOptionalToken(_tokenKind.TokenKind.AT);
+    const name = this.parseName();
+    let memberName;
+
+    if (!ofDirective && this.expectOptionalToken(_tokenKind.TokenKind.DOT)) {
+      memberName = this.parseName();
+    }
+
+    let argumentName;
+
+    if (
+      (ofDirective || memberName) &&
+      this.expectOptionalToken(_tokenKind.TokenKind.PAREN_L)
+    ) {
+      argumentName = this.parseName();
+      this.expectToken(_tokenKind.TokenKind.COLON);
+      this.expectToken(_tokenKind.TokenKind.PAREN_R);
+    }
+
+    if (ofDirective) {
+      if (argumentName) {
+        return this.node(start, {
+          kind: _kinds.Kind.DIRECTIVE_ARGUMENT_COORDINATE,
+          name,
+          argumentName,
+        });
+      }
+
+      return this.node(start, {
+        kind: _kinds.Kind.DIRECTIVE_COORDINATE,
+        name,
+      });
+    } else if (memberName) {
+      if (argumentName) {
+        return this.node(start, {
+          kind: _kinds.Kind.ARGUMENT_COORDINATE,
+          name,
+          fieldName: memberName,
+          argumentName,
+        });
+      }
+
+      return this.node(start, {
+        kind: _kinds.Kind.MEMBER_COORDINATE,
+        name,
+        memberName,
+      });
+    }
+
+    return this.node(start, {
+      kind: _kinds.Kind.TYPE_COORDINATE,
+      name,
+    });
   } // Core parsing utility functions
 
   /**

package/language/parser.mjs

@@ -3,6 +3,7 @@ import { Location, OperationTypeNode } from './ast.mjs';
 import { DirectiveLocation } from './directiveLocation.mjs';
 import { Kind } from './kinds.mjs';
 import { isPunctuatorTokenKind, Lexer } from './lexer.mjs';
+import { SchemaCoordinateLexer } from './schemaCoordinateLexer.mjs';
 import { isSource, Source } from './source.mjs';
 import { TokenKind } from './tokenKind.mjs';
 /**
@@ -70,6 +71,27 @@ export function parseType(source, options) {
   parser.expectToken(TokenKind.EOF);
   return type;
 }
+/**
+ * Given a string containing a GraphQL Schema Coordinate (ex. `Type.field`),
+ * parse the AST for that schema coordinate.
+ * Throws GraphQLError if a syntax error is encountered.
+ *
+ * Consider providing the results to the utility function:
+ * resolveASTSchemaCoordinate(). Or calling resolveSchemaCoordinate() directly
+ * with an unparsed source.
+ */
+
+export function parseSchemaCoordinate(source) {
+  const sourceObj = isSource(source) ? source : new Source(source);
+  const lexer = new SchemaCoordinateLexer(sourceObj);
+  const parser = new Parser(source, {
+    lexer,
+  });
+  parser.expectToken(TokenKind.SOF);
+  const coordinate = parser.parseSchemaCoordinate();
+  parser.expectToken(TokenKind.EOF);
+  return coordinate;
+}
 /**
  * This class is exported only to assist people in implementing their own parsers
  * without duplicating too much code and should be used only as last resort for cases
@@ -84,9 +106,16 @@ export function parseType(source, options) {
 
 export class Parser {
   constructor(source, options = {}) {
-    const sourceObj = isSource(source) ? source : new Source(source);
-    this._lexer = new Lexer(sourceObj);
-    this._options = options;
+    const { lexer, ..._options } = options;
+
+    if (lexer) {
+      this._lexer = lexer;
+    } else {
+      const sourceObj = isSource(source) ? source : new Source(source);
+      this._lexer = new Lexer(sourceObj);
+    }
+
+    this._options = _options;
     this._tokenCounter = 0;
   }
 
@@ -153,6 +182,14 @@ export class Parser {
       ? this._lexer.lookahead()
       : this._lexer.token;
 
+    if (hasDescription && keywordToken.kind === TokenKind.BRACE_L) {
+      throw syntaxError(
+        this._lexer.source,
+        this._lexer.token.start,
+        'Unexpected description, descriptions are not supported on shorthand queries.',
+      );
+    }
+
     if (keywordToken.kind === TokenKind.NAME) {
       switch (keywordToken.value) {
         case 'schema':
@@ -180,14 +217,6 @@ export class Parser {
           return this.parseDirectiveDefinition();
       }
 
-      if (hasDescription) {
-        throw syntaxError(
-          this._lexer.source,
-          this._lexer.token.start,
-          'Unexpected description, descriptions are supported only on type definitions.',
-        );
-      }
-
       switch (keywordToken.value) {
         case 'query':
         case 'mutation':
@@ -196,7 +225,17 @@ export class Parser {
 
         case 'fragment':
           return this.parseFragmentDefinition();
+      }
+
+      if (hasDescription) {
+        throw syntaxError(
+          this._lexer.source,
+          this._lexer.token.start,
+          'Unexpected description, only GraphQL definitions support descriptions.',
+        );
+      }
 
+      switch (keywordToken.value) {
         case 'extend':
           return this.parseTypeSystemExtension();
       }
@@ -218,6 +257,7 @@ export class Parser {
       return this.node(start, {
         kind: Kind.OPERATION_DEFINITION,
         operation: OperationTypeNode.QUERY,
+        description: undefined,
         name: undefined,
         variableDefinitions: [],
         directives: [],
@@ -225,6 +265,7 @@ export class Parser {
       });
     }
 
+    const description = this.parseDescription();
     const operation = this.parseOperationType();
     let name;
 
@@ -235,6 +276,7 @@ export class Parser {
     return this.node(start, {
       kind: Kind.OPERATION_DEFINITION,
       operation,
+      description,
       name,
       variableDefinitions: this.parseVariableDefinitions(),
       directives: this.parseDirectives(false),
@@ -279,6 +321,7 @@ export class Parser {
   parseVariableDefinition() {
     return this.node(this._lexer.token, {
       kind: Kind.VARIABLE_DEFINITION,
+      description: this.parseDescription(),
       variable: this.parseVariable(),
       type: (this.expectToken(TokenKind.COLON), this.parseTypeReference()),
       defaultValue: this.expectOptionalToken(TokenKind.EQUALS)
@@ -421,6 +464,7 @@ export class Parser {
 
   parseFragmentDefinition() {
     const start = this._lexer.token;
+    const description = this.parseDescription();
     this.expectKeyword('fragment'); // Legacy support for defining variables within fragments changes
     // the grammar of FragmentDefinition:
     //   - fragment FragmentName VariableDefinitions? on TypeCondition Directives? SelectionSet
@@ -428,6 +472,7 @@ export class Parser {
     if (this._options.allowLegacyFragmentVariables === true) {
       return this.node(start, {
         kind: Kind.FRAGMENT_DEFINITION,
+        description,
         name: this.parseFragmentName(),
         variableDefinitions: this.parseVariableDefinitions(),
         typeCondition: (this.expectKeyword('on'), this.parseNamedType()),
@@ -438,6 +483,7 @@ export class Parser {
 
     return this.node(start, {
       kind: Kind.FRAGMENT_DEFINITION,
+      description,
       name: this.parseFragmentName(),
       typeCondition: (this.expectKeyword('on'), this.parseNamedType()),
       directives: this.parseDirectives(false),
@@ -1323,6 +1369,72 @@ export class Parser {
     }
 
     throw this.unexpected(start);
+  } // Schema Coordinates
+
+  /**
+   * SchemaCoordinate :
+   *   - Name
+   *   - Name . Name
+   *   - Name . Name ( Name : )
+   *   - \@ Name
+   *   - \@ Name ( Name : )
+   */
+
+  parseSchemaCoordinate() {
+    const start = this._lexer.token;
+    const ofDirective = this.expectOptionalToken(TokenKind.AT);
+    const name = this.parseName();
+    let memberName;
+
+    if (!ofDirective && this.expectOptionalToken(TokenKind.DOT)) {
+      memberName = this.parseName();
+    }
+
+    let argumentName;
+
+    if (
+      (ofDirective || memberName) &&
+      this.expectOptionalToken(TokenKind.PAREN_L)
+    ) {
+      argumentName = this.parseName();
+      this.expectToken(TokenKind.COLON);
+      this.expectToken(TokenKind.PAREN_R);
+    }
+
+    if (ofDirective) {
+      if (argumentName) {
+        return this.node(start, {
+          kind: Kind.DIRECTIVE_ARGUMENT_COORDINATE,
+          name,
+          argumentName,
+        });
+      }
+
+      return this.node(start, {
+        kind: Kind.DIRECTIVE_COORDINATE,
+        name,
+      });
+    } else if (memberName) {
+      if (argumentName) {
+        return this.node(start, {
+          kind: Kind.ARGUMENT_COORDINATE,
+          name,
+          fieldName: memberName,
+          argumentName,
+        });
+      }
+
+      return this.node(start, {
+        kind: Kind.MEMBER_COORDINATE,
+        name,
+        memberName,
+      });
+    }
+
+    return this.node(start, {
+      kind: Kind.TYPE_COORDINATE,
+      name,
+    });
   } // Core parsing utility functions
 
   /**

package/language/predicates.d.ts

@@ -3,6 +3,7 @@ import type {
   ConstValueNode,
   DefinitionNode,
   ExecutableDefinitionNode,
+  SchemaCoordinateNode,
   SelectionNode,
   TypeDefinitionNode,
   TypeExtensionNode,
@@ -31,3 +32,6 @@ export declare function isTypeSystemExtensionNode(
 export declare function isTypeExtensionNode(
   node: ASTNode,
 ): node is TypeExtensionNode;
+export declare function isSchemaCoordinateNode(
+  node: ASTNode,
+): node is SchemaCoordinateNode;

package/language/predicates.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, '__esModule', {
 exports.isConstValueNode = isConstValueNode;
 exports.isDefinitionNode = isDefinitionNode;
 exports.isExecutableDefinitionNode = isExecutableDefinitionNode;
+exports.isSchemaCoordinateNode = isSchemaCoordinateNode;
 exports.isSelectionNode = isSelectionNode;
 exports.isTypeDefinitionNode = isTypeDefinitionNode;
 exports.isTypeExtensionNode = isTypeExtensionNode;
@@ -107,3 +108,13 @@ function isTypeExtensionNode(node) {
     node.kind === _kinds.Kind.INPUT_OBJECT_TYPE_EXTENSION
   );
 }
+
+function isSchemaCoordinateNode(node) {
+  return (
+    node.kind === _kinds.Kind.TYPE_COORDINATE ||
+    node.kind === _kinds.Kind.MEMBER_COORDINATE ||
+    node.kind === _kinds.Kind.ARGUMENT_COORDINATE ||
+    node.kind === _kinds.Kind.DIRECTIVE_COORDINATE ||
+    node.kind === _kinds.Kind.DIRECTIVE_ARGUMENT_COORDINATE
+  );
+}

package/language/predicates.mjs

@@ -79,3 +79,12 @@ export function isTypeExtensionNode(node) {
     node.kind === Kind.INPUT_OBJECT_TYPE_EXTENSION
   );
 }
+export function isSchemaCoordinateNode(node) {
+  return (
+    node.kind === Kind.TYPE_COORDINATE ||
+    node.kind === Kind.MEMBER_COORDINATE ||
+    node.kind === Kind.ARGUMENT_COORDINATE ||
+    node.kind === Kind.DIRECTIVE_COORDINATE ||
+    node.kind === Kind.DIRECTIVE_ARGUMENT_COORDINATE
+  );
+}

package/language/printer.js

@@ -33,22 +33,27 @@ const printDocASTReducer = {
   },
   OperationDefinition: {
     leave(node) {
-      const varDefs = wrap('(', join(node.variableDefinitions, ', '), ')');
-      const prefix = join(
-        [
-          node.operation,
-          join([node.name, varDefs]),
-          join(node.directives, ' '),
-        ],
-        ' ',
-      ); // Anonymous queries with no directives or variable definitions can use
+      const varDefs = hasMultilineItems(node.variableDefinitions)
+        ? wrap('(\n', join(node.variableDefinitions, '\n'), '\n)')
+        : wrap('(', join(node.variableDefinitions, ', '), ')');
+      const prefix =
+        wrap('', node.description, '\n') +
+        join(
+          [
+            node.operation,
+            join([node.name, varDefs]),
+            join(node.directives, ' '),
+          ],
+          ' ',
+        ); // Anonymous queries with no directives or variable definitions can use
       // the query short form.
 
       return (prefix === 'query' ? '' : prefix + ' ') + node.selectionSet;
     },
   },
   VariableDefinition: {
-    leave: ({ variable, type, defaultValue, directives }) =>
+    leave: ({ variable, type, defaultValue, directives, description }) =>
+      wrap('', description, '\n') +
       variable +
       ': ' +
       type +
@@ -91,9 +96,15 @@ const printDocASTReducer = {
       ),
   },
   FragmentDefinition: {
-    leave: (
-      { name, typeCondition, variableDefinitions, directives, selectionSet }, // Note: fragment variable definitions are experimental and may be changed
-    ) =>
+    leave: ({
+      name,
+      typeCondition,
+      variableDefinitions,
+      directives,
+      selectionSet,
+      description,
+    }) =>
+      wrap('', description, '\n') + // Note: fragment variable definitions are experimental and may be changed
       // or removed in the future.
       `fragment ${name}${wrap('(', join(variableDefinitions, ', '), ')')} ` +
       `on ${typeCondition} ${wrap('', join(directives, ' '), ' ')}` +
@@ -297,6 +308,24 @@ const printDocASTReducer = {
     leave: ({ name, directives, fields }) =>
       join(['extend input', name, join(directives, ' '), block(fields)], ' '),
   },
+  // Schema Coordinates
+  TypeCoordinate: {
+    leave: ({ name }) => name,
+  },
+  MemberCoordinate: {
+    leave: ({ name, memberName }) => join([name, wrap('.', memberName)]),
+  },
+  ArgumentCoordinate: {
+    leave: ({ name, fieldName, argumentName }) =>
+      join([name, wrap('.', fieldName), wrap('(', argumentName, ':)')]),
+  },
+  DirectiveCoordinate: {
+    leave: ({ name }) => join(['@', name]),
+  },
+  DirectiveArgumentCoordinate: {
+    leave: ({ name, argumentName }) =>
+      join(['@', name, wrap('(', argumentName, ':)')]),
+  },
 };
 /**
  * Given maybeArray, print an empty string if it is null or empty, otherwise

package/language/printer.mjs

@@ -23,22 +23,27 @@ const printDocASTReducer = {
   },
   OperationDefinition: {
     leave(node) {
-      const varDefs = wrap('(', join(node.variableDefinitions, ', '), ')');
-      const prefix = join(
-        [
-          node.operation,
-          join([node.name, varDefs]),
-          join(node.directives, ' '),
-        ],
-        ' ',
-      ); // Anonymous queries with no directives or variable definitions can use
+      const varDefs = hasMultilineItems(node.variableDefinitions)
+        ? wrap('(\n', join(node.variableDefinitions, '\n'), '\n)')
+        : wrap('(', join(node.variableDefinitions, ', '), ')');
+      const prefix =
+        wrap('', node.description, '\n') +
+        join(
+          [
+            node.operation,
+            join([node.name, varDefs]),
+            join(node.directives, ' '),
+          ],
+          ' ',
+        ); // Anonymous queries with no directives or variable definitions can use
       // the query short form.
 
       return (prefix === 'query' ? '' : prefix + ' ') + node.selectionSet;
     },
   },
   VariableDefinition: {
-    leave: ({ variable, type, defaultValue, directives }) =>
+    leave: ({ variable, type, defaultValue, directives, description }) =>
+      wrap('', description, '\n') +
       variable +
       ': ' +
       type +
@@ -81,9 +86,15 @@ const printDocASTReducer = {
       ),
   },
   FragmentDefinition: {
-    leave: (
-      { name, typeCondition, variableDefinitions, directives, selectionSet }, // Note: fragment variable definitions are experimental and may be changed
-    ) =>
+    leave: ({
+      name,
+      typeCondition,
+      variableDefinitions,
+      directives,
+      selectionSet,
+      description,
+    }) =>
+      wrap('', description, '\n') + // Note: fragment variable definitions are experimental and may be changed
       // or removed in the future.
       `fragment ${name}${wrap('(', join(variableDefinitions, ', '), ')')} ` +
       `on ${typeCondition} ${wrap('', join(directives, ' '), ' ')}` +
@@ -285,6 +296,24 @@ const printDocASTReducer = {
     leave: ({ name, directives, fields }) =>
       join(['extend input', name, join(directives, ' '), block(fields)], ' '),
   },
+  // Schema Coordinates
+  TypeCoordinate: {
+    leave: ({ name }) => name,
+  },
+  MemberCoordinate: {
+    leave: ({ name, memberName }) => join([name, wrap('.', memberName)]),
+  },
+  ArgumentCoordinate: {
+    leave: ({ name, fieldName, argumentName }) =>
+      join([name, wrap('.', fieldName), wrap('(', argumentName, ':)')]),
+  },
+  DirectiveCoordinate: {
+    leave: ({ name }) => join(['@', name]),
+  },
+  DirectiveArgumentCoordinate: {
+    leave: ({ name, argumentName }) =>
+      join(['@', name, wrap('(', argumentName, ':)')]),
+  },
 };
 /**
  * Given maybeArray, print an empty string if it is null or empty, otherwise