graphql 16.11.0 → 16.12.0

package/language/lexer.mjs

@@ -3,6 +3,13 @@ import { Token } from './ast.mjs';
 import { dedentBlockStringLines } from './blockString.mjs';
 import { isDigit, isNameContinue, isNameStart } from './characterClasses.mjs';
 import { TokenKind } from './tokenKind.mjs';
+/**
+ * A Lexer interface which provides common properties and methods required for
+ * lexing GraphQL source.
+ *
+ * @internal
+ */
+
 /**
  * Given a Source object, creates a Lexer for that source.
  * A Lexer is a stateful stream generator in that every time
@@ -11,7 +18,6 @@ import { TokenKind } from './tokenKind.mjs';
  * EOF, after which the lexer will repeatedly return the same EOF token
  * whenever called.
  */
-
 export class Lexer {
   /**
    * The previously focused non-ignored token.
@@ -87,6 +93,7 @@ export function isPunctuatorTokenKind(kind) {
     kind === TokenKind.AMP ||
     kind === TokenKind.PAREN_L ||
     kind === TokenKind.PAREN_R ||
+    kind === TokenKind.DOT ||
     kind === TokenKind.SPREAD ||
     kind === TokenKind.COLON ||
     kind === TokenKind.EQUALS ||
@@ -141,9 +148,11 @@ function isTrailingSurrogate(code) {
  *
  * Printable ASCII is printed quoted, while other points are printed in Unicode
  * code point form (ie. U+1234).
+ *
+ * @internal
  */
 
-function printCodePointAt(lexer, location) {
+export function printCodePointAt(lexer, location) {
   const code = lexer.source.body.codePointAt(location);
 
   if (code === undefined) {
@@ -158,9 +167,11 @@ function printCodePointAt(lexer, location) {
 }
 /**
  * Create a token with line and column location information.
+ *
+ * @internal
  */
 
-function createToken(lexer, kind, start, end, value) {
+export function createToken(lexer, kind, start, end, value) {
   const line = lexer.line;
   const col = 1 + start - lexer.lineStart;
   return new Token(kind, start, end, line, col, value);
@@ -875,9 +886,11 @@ function readBlockString(lexer, start) {
  * Name ::
  *   - NameStart NameContinue* [lookahead != NameContinue]
  * ```
+ *
+ * @internal
  */
 
-function readName(lexer, start) {
+export function readName(lexer, start) {
   const body = lexer.source.body;
   const bodyLength = body.length;
   let position = start + 1;

package/language/parser.d.ts

@@ -36,6 +36,7 @@ import type {
   OperationTypeDefinitionNode,
   ScalarTypeDefinitionNode,
   ScalarTypeExtensionNode,
+  SchemaCoordinateNode,
   SchemaDefinitionNode,
   SchemaExtensionNode,
   SelectionNode,
@@ -51,7 +52,7 @@ import type {
   VariableNode,
 } from './ast';
 import { Location, OperationTypeNode } from './ast';
-import { Lexer } from './lexer';
+import type { LexerInterface } from './lexer';
 import { Source } from './source';
 import { TokenKind } from './tokenKind';
 /**
@@ -88,6 +89,11 @@ export interface ParseOptions {
    * ```
    */
   allowLegacyFragmentVariables?: boolean;
+  /**
+   * You may override the Lexer class used to lex the source; this is used by
+   * schema coordinates to introduce a lexer with a restricted syntax.
+   */
+  lexer?: LexerInterface | undefined;
 }
 /**
  * Given a GraphQL source, parses it into a Document.
@@ -133,6 +139,18 @@ export declare function parseType(
   source: string | Source,
   options?: ParseOptions | undefined,
 ): TypeNode;
+/**
+ * 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 declare function parseSchemaCoordinate(
+  source: string | Source,
+): SchemaCoordinateNode;
 /**
  * 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
@@ -145,8 +163,8 @@ export declare function parseType(
  * @internal
  */
 export declare class Parser {
-  protected _options: ParseOptions;
-  protected _lexer: Lexer;
+  protected _options: Omit<ParseOptions, 'lexer'>;
+  protected _lexer: LexerInterface;
   protected _tokenCounter: number;
   constructor(source: string | Source, options?: ParseOptions);
   get tokenCount(): number;
@@ -490,6 +508,15 @@ export declare class Parser {
    */
   parseDirectiveLocations(): Array<NameNode>;
   parseDirectiveLocation(): NameNode;
+  /**
+   * SchemaCoordinate :
+   *   - Name
+   *   - Name . Name
+   *   - Name . Name ( Name : )
+   *   - \@ Name
+   *   - \@ Name ( Name : )
+   */
+  parseSchemaCoordinate(): SchemaCoordinateNode;
   /**
    * Returns a node that, if configured to do so, sets a "loc" field as a
    * location object, used to identify the place in the source that created a

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
+  );
+}