graphql 16.13.2 → 16.14.1

package/language/parser.js

@@ -26,9 +26,44 @@ var _source = require('./source.js');
 
 var _tokenKind = require('./tokenKind.js');
 
+/** @category Parsing */
+
 /**
  * Given a GraphQL source, parses it into a Document.
  * Throws GraphQLError if a syntax error is encountered.
+ * @param source - A GraphQL source string or source object.
+ * @param options - Optional parser configuration.
+ * @returns The parsed GraphQL document AST.
+ * @example
+ * ```ts
+ * // Parse a GraphQL document with the default parser options.
+ * import { parse } from 'graphql/language';
+ *
+ * const document = parse('{ hero { name } }');
+ *
+ * document.kind; // => 'Document'
+ * ```
+ * @example
+ * ```ts
+ * // This variant enables parser options and provides an explicit lexer.
+ * import { Lexer, Source, parse } from 'graphql/language';
+ *
+ * const document = parse('fragment A($var: Boolean) on Query { field }', {
+ *   allowLegacyFragmentVariables: true,
+ *   maxTokens: 20,
+ *   noLocation: true,
+ * });
+ * const directiveDocument = parse('directive @foo @bar on FIELD', {
+ *   experimentalDirectivesOnDirectiveDefinitions: true,
+ * });
+ * const source = new Source('{ hero }');
+ * const lexerDocument = parse(source, { lexer: new Lexer(source) });
+ *
+ * document.definitions[0].kind; // => 'FragmentDefinition'
+ * document.loc; // => undefined
+ * directiveDocument.definitions[0].kind; // => 'DirectiveDefinition'
+ * lexerDocument.definitions[0].kind; // => 'OperationDefinition'
+ * ```
  */
 function parse(source, options) {
   const parser = new Parser(source, options);
@@ -48,6 +83,17 @@ function parse(source, options) {
  * in isolation of complete GraphQL documents.
  *
  * Consider providing the results to the utility function: valueFromAST().
+ * @param source - A GraphQL source string or source object containing a value.
+ * @param options - Optional parser configuration.
+ * @returns The parsed GraphQL value AST.
+ * @example
+ * ```ts
+ * import { parseValue } from 'graphql/language';
+ *
+ * const value = parseValue('[42]');
+ *
+ * value.kind; // => 'ListValue'
+ * ```
  */
 
 function parseValue(source, options) {
@@ -60,6 +106,18 @@ function parseValue(source, options) {
 /**
  * Similar to parseValue(), but raises a parse error if it encounters a
  * variable. The return type will be a constant value.
+ * @param source - A GraphQL source string or source object containing a constant value.
+ * @param options - Optional parser configuration.
+ * @returns The parsed GraphQL constant value AST.
+ * @example
+ * ```ts
+ * import { parseConstValue } from 'graphql/language';
+ *
+ * const value = parseConstValue('{ enabled: true }');
+ *
+ * value.kind; // => 'ObjectValue'
+ * parseConstValue('$variable'); // throws an error
+ * ```
  */
 
 function parseConstValue(source, options) {
@@ -78,6 +136,17 @@ function parseConstValue(source, options) {
  * in isolation of complete GraphQL documents.
  *
  * Consider providing the results to the utility function: typeFromAST().
+ * @param source - A GraphQL source string or source object containing a type reference.
+ * @param options - Optional parser configuration.
+ * @returns The parsed GraphQL type AST.
+ * @example
+ * ```ts
+ * import { parseType } from 'graphql/language';
+ *
+ * const type = parseType('[String!]');
+ *
+ * type.kind; // => 'ListType'
+ * ```
  */
 
 function parseType(source, options) {
@@ -95,6 +164,16 @@ function parseType(source, options) {
  * Consider providing the results to the utility function:
  * resolveASTSchemaCoordinate(). Or calling resolveSchemaCoordinate() directly
  * with an unparsed source.
+ * @param source - A GraphQL source string or source object containing a schema coordinate.
+ * @returns The parsed GraphQL schema coordinate AST.
+ * @example
+ * ```ts
+ * import { parseSchemaCoordinate } from 'graphql/language';
+ *
+ * const coordinate = parseSchemaCoordinate('Query.hero');
+ *
+ * coordinate.kind; // => 'MemberCoordinate'
+ * ```
  */
 
 function parseSchemaCoordinate(source) {
@@ -144,6 +223,8 @@ class Parser {
   }
   /**
    * Converts a name lex token into a name parse node.
+   *
+   * @internal
    */
 
   parseName() {
@@ -156,6 +237,8 @@ class Parser {
 
   /**
    * Document : Definition+
+   *
+   * @internal
    */
 
   parseDocument() {
@@ -190,6 +273,8 @@ class Parser {
    *   - UnionTypeDefinition
    *   - EnumTypeDefinition
    *   - InputObjectTypeDefinition
+   *
+   * @internal
    */
 
   parseDefinition() {
@@ -268,6 +353,8 @@ class Parser {
    * OperationDefinition :
    *  - SelectionSet
    *  - OperationType Name? VariableDefinitions? Directives? SelectionSet
+   *
+   * @internal
    */
 
   parseOperationDefinition() {
@@ -305,6 +392,8 @@ class Parser {
   }
   /**
    * OperationType : one of query mutation subscription
+   *
+   * @internal
    */
 
   parseOperationType() {
@@ -325,6 +414,8 @@ class Parser {
   }
   /**
    * VariableDefinitions : ( VariableDefinition+ )
+   *
+   * @internal
    */
 
   parseVariableDefinitions() {
@@ -336,6 +427,8 @@ class Parser {
   }
   /**
    * VariableDefinition : Variable : Type DefaultValue? Directives[Const]?
+   *
+   * @internal
    */
 
   parseVariableDefinition() {
@@ -354,6 +447,8 @@ class Parser {
   }
   /**
    * Variable : $ Name
+   *
+   * @internal
    */
 
   parseVariable() {
@@ -368,6 +463,8 @@ class Parser {
    * ```
    * SelectionSet : { Selection+ }
    * ```
+   *
+   * @internal
    */
 
   parseSelectionSet() {
@@ -385,6 +482,8 @@ class Parser {
    *   - Field
    *   - FragmentSpread
    *   - InlineFragment
+   *
+   * @internal
    */
 
   parseSelection() {
@@ -396,6 +495,8 @@ class Parser {
    * Field : Alias? Name Arguments? Directives? SelectionSet?
    *
    * Alias : Name :
+   *
+   * @internal
    */
 
   parseField() {
@@ -424,6 +525,8 @@ class Parser {
   }
   /**
    * Arguments[Const] : ( Argument[?Const]+ )
+   *
+   * @internal
    */
 
   parseArguments(isConst) {
@@ -436,6 +539,8 @@ class Parser {
   }
   /**
    * Argument[Const] : Name : Value[?Const]
+   *
+   * @internal
    */
 
   parseArgument(isConst = false) {
@@ -459,6 +564,8 @@ class Parser {
    * FragmentSpread : ... FragmentName Directives?
    *
    * InlineFragment : ... TypeCondition? Directives? SelectionSet
+   *
+   * @internal
    */
 
   parseFragment() {
@@ -486,6 +593,8 @@ class Parser {
    *   - fragment FragmentName on TypeCondition Directives? SelectionSet
    *
    * TypeCondition : NamedType
+   *
+   * @internal
    */
 
   parseFragmentDefinition() {
@@ -518,6 +627,8 @@ class Parser {
   }
   /**
    * FragmentName : Name but not `on`
+   *
+   * @internal
    */
 
   parseFragmentName() {
@@ -545,6 +656,8 @@ class Parser {
    * NullValue : `null`
    *
    * EnumValue : Name but not `true`, `false` or `null`
+   *
+   * @internal
    */
 
   parseValueLiteral(isConst) {
@@ -643,6 +756,8 @@ class Parser {
    * ListValue[Const] :
    *   - [ ]
    *   - [ Value[?Const]+ ]
+   *
+   * @internal
    */
 
   parseList(isConst) {
@@ -663,6 +778,8 @@ class Parser {
    *   - { }
    *   - { ObjectField[?Const]+ }
    * ```
+   *
+   * @internal
    */
 
   parseObject(isConst) {
@@ -679,6 +796,8 @@ class Parser {
   }
   /**
    * ObjectField[Const] : Name : Value[?Const]
+   *
+   * @internal
    */
 
   parseObjectField(isConst) {
@@ -694,6 +813,8 @@ class Parser {
 
   /**
    * Directives[Const] : Directive[?Const]+
+   *
+   * @internal
    */
 
   parseDirectives(isConst) {
@@ -713,6 +834,8 @@ class Parser {
    * ```
    * Directive[Const] : @ Name Arguments[?Const]?
    * ```
+   *
+   * @internal
    */
 
   parseDirective(isConst) {
@@ -730,6 +853,8 @@ class Parser {
    *   - NamedType
    *   - ListType
    *   - NonNullType
+   *
+   * @internal
    */
 
   parseTypeReference() {
@@ -758,6 +883,8 @@ class Parser {
   }
   /**
    * NamedType : Name
+   *
+   * @internal
    */
 
   parseNamedType() {
@@ -775,6 +902,8 @@ class Parser {
   }
   /**
    * Description : StringValue
+   *
+   * @internal
    */
 
   parseDescription() {
@@ -786,6 +915,8 @@ class Parser {
    * ```
    * SchemaDefinition : Description? schema Directives[Const]? { OperationTypeDefinition+ }
    * ```
+   *
+   * @internal
    */
 
   parseSchemaDefinition() {
@@ -807,6 +938,8 @@ class Parser {
   }
   /**
    * OperationTypeDefinition : OperationType : NamedType
+   *
+   * @internal
    */
 
   parseOperationTypeDefinition() {
@@ -822,6 +955,8 @@ class Parser {
   }
   /**
    * ScalarTypeDefinition : Description? scalar Name Directives[Const]?
+   *
+   * @internal
    */
 
   parseScalarTypeDefinition() {
@@ -841,6 +976,8 @@ class Parser {
    * ObjectTypeDefinition :
    *   Description?
    *   type Name ImplementsInterfaces? Directives[Const]? FieldsDefinition?
+   *
+   * @internal
    */
 
   parseObjectTypeDefinition() {
@@ -864,6 +1001,8 @@ class Parser {
    * ImplementsInterfaces :
    *   - implements `&`? NamedType
    *   - ImplementsInterfaces & NamedType
+   *
+   * @internal
    */
 
   parseImplementsInterfaces() {
@@ -875,6 +1014,8 @@ class Parser {
    * ```
    * FieldsDefinition : { FieldDefinition+ }
    * ```
+   *
+   * @internal
    */
 
   parseFieldsDefinition() {
@@ -887,6 +1028,8 @@ class Parser {
   /**
    * FieldDefinition :
    *   - Description? Name ArgumentsDefinition? : Type Directives[Const]?
+   *
+   * @internal
    */
 
   parseFieldDefinition() {
@@ -908,6 +1051,8 @@ class Parser {
   }
   /**
    * ArgumentsDefinition : ( InputValueDefinition+ )
+   *
+   * @internal
    */
 
   parseArgumentDefs() {
@@ -920,6 +1065,8 @@ class Parser {
   /**
    * InputValueDefinition :
    *   - Description? Name : Type DefaultValue? Directives[Const]?
+   *
+   * @internal
    */
 
   parseInputValueDef() {
@@ -947,6 +1094,8 @@ class Parser {
   /**
    * InterfaceTypeDefinition :
    *   - Description? interface Name Directives[Const]? FieldsDefinition?
+   *
+   * @internal
    */
 
   parseInterfaceTypeDefinition() {
@@ -969,6 +1118,8 @@ class Parser {
   /**
    * UnionTypeDefinition :
    *   - Description? union Name Directives[Const]? UnionMemberTypes?
+   *
+   * @internal
    */
 
   parseUnionTypeDefinition() {
@@ -990,6 +1141,8 @@ class Parser {
    * UnionMemberTypes :
    *   - = `|`? NamedType
    *   - UnionMemberTypes | NamedType
+   *
+   * @internal
    */
 
   parseUnionMemberTypes() {
@@ -1000,6 +1153,8 @@ class Parser {
   /**
    * EnumTypeDefinition :
    *   - Description? enum Name Directives[Const]? EnumValuesDefinition?
+   *
+   * @internal
    */
 
   parseEnumTypeDefinition() {
@@ -1021,6 +1176,8 @@ class Parser {
    * ```
    * EnumValuesDefinition : { EnumValueDefinition+ }
    * ```
+   *
+   * @internal
    */
 
   parseEnumValuesDefinition() {
@@ -1032,6 +1189,8 @@ class Parser {
   }
   /**
    * EnumValueDefinition : Description? EnumValue Directives[Const]?
+   *
+   * @internal
    */
 
   parseEnumValueDefinition() {
@@ -1048,6 +1207,8 @@ class Parser {
   }
   /**
    * EnumValue : Name but not `true`, `false` or `null`
+   *
+   * @internal
    */
 
   parseEnumValueName() {
@@ -1070,6 +1231,8 @@ class Parser {
   /**
    * InputObjectTypeDefinition :
    *   - Description? input Name Directives[Const]? InputFieldsDefinition?
+   *
+   * @internal
    */
 
   parseInputObjectTypeDefinition() {
@@ -1091,6 +1254,8 @@ class Parser {
    * ```
    * InputFieldsDefinition : { InputValueDefinition+ }
    * ```
+   *
+   * @internal
    */
 
   parseInputFieldsDefinition() {
@@ -1112,6 +1277,9 @@ class Parser {
    *   - UnionTypeExtension
    *   - EnumTypeExtension
    *   - InputObjectTypeDefinition
+   *   - DirectiveDefinitionExtension
+   *
+   * @internal
    */
 
   parseTypeSystemExtension() {
@@ -1139,6 +1307,13 @@ class Parser {
 
         case 'input':
           return this.parseInputObjectTypeExtension();
+
+        case 'directive':
+          if (this._options.experimentalDirectivesOnDirectiveDefinitions) {
+            return this.parseDirectiveDefinitionExtension();
+          }
+
+          break;
       }
     }
 
@@ -1150,6 +1325,8 @@ class Parser {
    *  - extend schema Directives[Const]? { OperationTypeDefinition+ }
    *  - extend schema Directives[Const]
    * ```
+   *
+   * @internal
    */
 
   parseSchemaExtension() {
@@ -1176,6 +1353,8 @@ class Parser {
   /**
    * ScalarTypeExtension :
    *   - extend scalar Name Directives[Const]
+   *
+   * @internal
    */
 
   parseScalarTypeExtension() {
@@ -1200,6 +1379,8 @@ class Parser {
    *  - extend type Name ImplementsInterfaces? Directives[Const]? FieldsDefinition
    *  - extend type Name ImplementsInterfaces? Directives[Const]
    *  - extend type Name ImplementsInterfaces
+   *
+   * @internal
    */
 
   parseObjectTypeExtension() {
@@ -1232,6 +1413,8 @@ class Parser {
    *  - extend interface Name ImplementsInterfaces? Directives[Const]? FieldsDefinition
    *  - extend interface Name ImplementsInterfaces? Directives[Const]
    *  - extend interface Name ImplementsInterfaces
+   *
+   * @internal
    */
 
   parseInterfaceTypeExtension() {
@@ -1263,6 +1446,8 @@ class Parser {
    * UnionTypeExtension :
    *   - extend union Name Directives[Const]? UnionMemberTypes
    *   - extend union Name Directives[Const]
+   *
+   * @internal
    */
 
   parseUnionTypeExtension() {
@@ -1288,6 +1473,8 @@ class Parser {
    * EnumTypeExtension :
    *   - extend enum Name Directives[Const]? EnumValuesDefinition
    *   - extend enum Name Directives[Const]
+   *
+   * @internal
    */
 
   parseEnumTypeExtension() {
@@ -1313,6 +1500,8 @@ class Parser {
    * InputObjectTypeExtension :
    *   - extend input Name Directives[Const]? InputFieldsDefinition
    *   - extend input Name Directives[Const]
+   *
+   * @internal
    */
 
   parseInputObjectTypeExtension() {
@@ -1334,11 +1523,32 @@ class Parser {
       fields,
     });
   }
+
+  parseDirectiveDefinitionExtension() {
+    const start = this._lexer.token;
+    this.expectKeyword('extend');
+    this.expectKeyword('directive');
+    this.expectToken(_tokenKind.TokenKind.AT);
+    const name = this.parseName();
+    const directives = this.parseConstDirectives();
+
+    if (directives.length === 0) {
+      throw this.unexpected();
+    }
+
+    return this.node(start, {
+      kind: _kinds.Kind.DIRECTIVE_EXTENSION,
+      name,
+      directives,
+    });
+  }
   /**
    * ```
    * DirectiveDefinition :
    *   - Description? directive @ Name ArgumentsDefinition? `repeatable`? on DirectiveLocations
    * ```
+   *
+   * @internal
    */
 
   parseDirectiveDefinition() {
@@ -1348,6 +1558,10 @@ class Parser {
     this.expectToken(_tokenKind.TokenKind.AT);
     const name = this.parseName();
     const args = this.parseArgumentDefs();
+    const directives = this._options
+      .experimentalDirectivesOnDirectiveDefinitions
+      ? this.parseConstDirectives()
+      : [];
     const repeatable = this.expectOptionalKeyword('repeatable');
     this.expectKeyword('on');
     const locations = this.parseDirectiveLocations();
@@ -1356,6 +1570,7 @@ class Parser {
       description,
       name,
       arguments: args,
+      directives,
       repeatable,
       locations,
     });
@@ -1364,6 +1579,8 @@ class Parser {
    * DirectiveLocations :
    *   - `|`? DirectiveLocation
    *   - DirectiveLocations | DirectiveLocation
+   *
+   * @internal
    */
 
   parseDirectiveLocations() {
@@ -1398,6 +1615,7 @@ class Parser {
    *   `ENUM_VALUE`
    *   `INPUT_OBJECT`
    *   `INPUT_FIELD_DEFINITION`
+   *   `DIRECTIVE_DEFINITION`
    */
 
   parseDirectiveLocation() {
@@ -1423,6 +1641,19 @@ class Parser {
    *   - Name . Name ( Name : )
    *   - \@ Name
    *   - \@ Name ( Name : )
+   * @returns Parsed schema coordinate AST.
+   * @example
+   * ```ts
+   * import { Parser, Source } from 'graphql/language';
+   *
+   * const typeCoordinate = new Parser(new Source('User.name')).parseSchemaCoordinate();
+   * const directiveCoordinate = new Parser(new Source('@include(if:)')).parseSchemaCoordinate();
+   *
+   * typeCoordinate.name.value; // => 'User'
+   * typeCoordinate.memberName?.value; // => 'name'
+   * directiveCoordinate.name.value; // => 'deprecated'
+   * directiveCoordinate.argumentName?.value; // => 'reason'
+   * ```
    */
 
   parseSchemaCoordinate() {
@@ -1486,6 +1717,8 @@ class Parser {
    * 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
    * given parsed object.
+   *
+   * @internal
    */
 
   node(startToken, node) {
@@ -1501,6 +1734,8 @@ class Parser {
   }
   /**
    * Determines if the next token is of a given kind
+   *
+   * @internal
    */
 
   peek(kind) {
@@ -1509,6 +1744,8 @@ class Parser {
   /**
    * If the next token is of the given kind, return that token after advancing the lexer.
    * Otherwise, do not change the parser state and throw an error.
+   *
+   * @internal
    */
 
   expectToken(kind) {
@@ -1528,6 +1765,8 @@ class Parser {
   /**
    * If the next token is of the given kind, return "true" after advancing the lexer.
    * Otherwise, do not change the parser state and return "false".
+   *
+   * @internal
    */
 
   expectOptionalToken(kind) {
@@ -1543,6 +1782,8 @@ class Parser {
   /**
    * If the next token is a given keyword, advance the lexer.
    * Otherwise, do not change the parser state and throw an error.
+   *
+   * @internal
    */
 
   expectKeyword(value) {
@@ -1561,6 +1802,8 @@ class Parser {
   /**
    * If the next token is a given keyword, return "true" after advancing the lexer.
    * Otherwise, do not change the parser state and return "false".
+   *
+   * @internal
    */
 
   expectOptionalKeyword(value) {
@@ -1575,6 +1818,8 @@ class Parser {
   }
   /**
    * Helper function for creating an error when an unexpected lexed token is encountered.
+   *
+   * @internal
    */
 
   unexpected(atToken) {
@@ -1590,6 +1835,8 @@ class Parser {
    * Returns a possibly empty list of parse nodes, determined by the parseFn.
    * This list begins with a lex token of openKind and ends with a lex token of closeKind.
    * Advances the parser to the next lex token after the closing token.
+   *
+   * @internal
    */
 
   any(openKind, parseFn, closeKind) {
@@ -1607,6 +1854,8 @@ class Parser {
    * It can be empty only if open token is missing otherwise it will always return non-empty list
    * that begins with a lex token of openKind and ends with a lex token of closeKind.
    * Advances the parser to the next lex token after the closing token.
+   *
+   * @internal
    */
 
   optionalMany(openKind, parseFn, closeKind) {
@@ -1626,6 +1875,8 @@ class Parser {
    * Returns a non-empty list of parse nodes, determined by the parseFn.
    * This list begins with a lex token of openKind and ends with a lex token of closeKind.
    * Advances the parser to the next lex token after the closing token.
+   *
+   * @internal
    */
 
   many(openKind, parseFn, closeKind) {
@@ -1642,6 +1893,8 @@ class Parser {
    * Returns a non-empty list of parse nodes, determined by the parseFn.
    * This list may begin with a lex token of delimiterKind followed by items separated by lex tokens of tokenKind.
    * Advances the parser to the next lex token after last item in the list.
+   *
+   * @internal
    */
 
   delimitedMany(delimiterKind, parseFn) {
@@ -1675,6 +1928,8 @@ class Parser {
 }
 /**
  * A helper function to describe a token as a string for debugging.
+ *
+ * @internal
  */
 
 exports.Parser = Parser;
@@ -1685,6 +1940,8 @@ function getTokenDesc(token) {
 }
 /**
  * A helper function to describe a token kind as a string for debugging.
+ *
+ * @internal
  */
 
 function getTokenKindDesc(kind) {