graphql 16.13.2 → 16.14.1

package/language/parser.mjs

@@ -1,3 +1,4 @@
+/** @category Parsing */
 import { syntaxError } from '../error/syntaxError.mjs';
 import { Location, OperationTypeNode } from './ast.mjs';
 import { DirectiveLocation } from './directiveLocation.mjs';
@@ -6,13 +7,44 @@ import { isPunctuatorTokenKind, Lexer } from './lexer.mjs';
 import { SchemaCoordinateLexer } from './schemaCoordinateLexer.mjs';
 import { isSource, Source } from './source.mjs';
 import { TokenKind } from './tokenKind.mjs';
-/**
- * Configuration options to control parser behavior
- */
+/** Configuration options to control parser behavior */
 
 /**
  * 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'
+ * ```
  */
 export function parse(source, options) {
   const parser = new Parser(source, options);
@@ -32,6 +64,17 @@ export 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'
+ * ```
  */
 
 export function parseValue(source, options) {
@@ -44,6 +87,18 @@ export 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
+ * ```
  */
 
 export function parseConstValue(source, options) {
@@ -62,6 +117,17 @@ export 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'
+ * ```
  */
 
 export function parseType(source, options) {
@@ -79,6 +145,16 @@ export 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'
+ * ```
  */
 
 export function parseSchemaCoordinate(source) {
@@ -124,6 +200,8 @@ export class Parser {
   }
   /**
    * Converts a name lex token into a name parse node.
+   *
+   * @internal
    */
 
   parseName() {
@@ -136,6 +214,8 @@ export class Parser {
 
   /**
    * Document : Definition+
+   *
+   * @internal
    */
 
   parseDocument() {
@@ -170,6 +250,8 @@ export class Parser {
    *   - UnionTypeDefinition
    *   - EnumTypeDefinition
    *   - InputObjectTypeDefinition
+   *
+   * @internal
    */
 
   parseDefinition() {
@@ -248,6 +330,8 @@ export class Parser {
    * OperationDefinition :
    *  - SelectionSet
    *  - OperationType Name? VariableDefinitions? Directives? SelectionSet
+   *
+   * @internal
    */
 
   parseOperationDefinition() {
@@ -285,6 +369,8 @@ export class Parser {
   }
   /**
    * OperationType : one of query mutation subscription
+   *
+   * @internal
    */
 
   parseOperationType() {
@@ -305,6 +391,8 @@ export class Parser {
   }
   /**
    * VariableDefinitions : ( VariableDefinition+ )
+   *
+   * @internal
    */
 
   parseVariableDefinitions() {
@@ -316,6 +404,8 @@ export class Parser {
   }
   /**
    * VariableDefinition : Variable : Type DefaultValue? Directives[Const]?
+   *
+   * @internal
    */
 
   parseVariableDefinition() {
@@ -332,6 +422,8 @@ export class Parser {
   }
   /**
    * Variable : $ Name
+   *
+   * @internal
    */
 
   parseVariable() {
@@ -346,6 +438,8 @@ export class Parser {
    * ```
    * SelectionSet : { Selection+ }
    * ```
+   *
+   * @internal
    */
 
   parseSelectionSet() {
@@ -363,6 +457,8 @@ export class Parser {
    *   - Field
    *   - FragmentSpread
    *   - InlineFragment
+   *
+   * @internal
    */
 
   parseSelection() {
@@ -374,6 +470,8 @@ export class Parser {
    * Field : Alias? Name Arguments? Directives? SelectionSet?
    *
    * Alias : Name :
+   *
+   * @internal
    */
 
   parseField() {
@@ -402,6 +500,8 @@ export class Parser {
   }
   /**
    * Arguments[Const] : ( Argument[?Const]+ )
+   *
+   * @internal
    */
 
   parseArguments(isConst) {
@@ -410,6 +510,8 @@ export class Parser {
   }
   /**
    * Argument[Const] : Name : Value[?Const]
+   *
+   * @internal
    */
 
   parseArgument(isConst = false) {
@@ -433,6 +535,8 @@ export class Parser {
    * FragmentSpread : ... FragmentName Directives?
    *
    * InlineFragment : ... TypeCondition? Directives? SelectionSet
+   *
+   * @internal
    */
 
   parseFragment() {
@@ -460,6 +564,8 @@ export class Parser {
    *   - fragment FragmentName on TypeCondition Directives? SelectionSet
    *
    * TypeCondition : NamedType
+   *
+   * @internal
    */
 
   parseFragmentDefinition() {
@@ -492,6 +598,8 @@ export class Parser {
   }
   /**
    * FragmentName : Name but not `on`
+   *
+   * @internal
    */
 
   parseFragmentName() {
@@ -519,6 +627,8 @@ export class Parser {
    * NullValue : `null`
    *
    * EnumValue : Name but not `true`, `false` or `null`
+   *
+   * @internal
    */
 
   parseValueLiteral(isConst) {
@@ -617,6 +727,8 @@ export class Parser {
    * ListValue[Const] :
    *   - [ ]
    *   - [ Value[?Const]+ ]
+   *
+   * @internal
    */
 
   parseList(isConst) {
@@ -633,6 +745,8 @@ export class Parser {
    *   - { }
    *   - { ObjectField[?Const]+ }
    * ```
+   *
+   * @internal
    */
 
   parseObject(isConst) {
@@ -645,6 +759,8 @@ export class Parser {
   }
   /**
    * ObjectField[Const] : Name : Value[?Const]
+   *
+   * @internal
    */
 
   parseObjectField(isConst) {
@@ -660,6 +776,8 @@ export class Parser {
 
   /**
    * Directives[Const] : Directive[?Const]+
+   *
+   * @internal
    */
 
   parseDirectives(isConst) {
@@ -679,6 +797,8 @@ export class Parser {
    * ```
    * Directive[Const] : @ Name Arguments[?Const]?
    * ```
+   *
+   * @internal
    */
 
   parseDirective(isConst) {
@@ -696,6 +816,8 @@ export class Parser {
    *   - NamedType
    *   - ListType
    *   - NonNullType
+   *
+   * @internal
    */
 
   parseTypeReference() {
@@ -724,6 +846,8 @@ export class Parser {
   }
   /**
    * NamedType : Name
+   *
+   * @internal
    */
 
   parseNamedType() {
@@ -738,6 +862,8 @@ export class Parser {
   }
   /**
    * Description : StringValue
+   *
+   * @internal
    */
 
   parseDescription() {
@@ -749,6 +875,8 @@ export class Parser {
    * ```
    * SchemaDefinition : Description? schema Directives[Const]? { OperationTypeDefinition+ }
    * ```
+   *
+   * @internal
    */
 
   parseSchemaDefinition() {
@@ -770,6 +898,8 @@ export class Parser {
   }
   /**
    * OperationTypeDefinition : OperationType : NamedType
+   *
+   * @internal
    */
 
   parseOperationTypeDefinition() {
@@ -785,6 +915,8 @@ export class Parser {
   }
   /**
    * ScalarTypeDefinition : Description? scalar Name Directives[Const]?
+   *
+   * @internal
    */
 
   parseScalarTypeDefinition() {
@@ -804,6 +936,8 @@ export class Parser {
    * ObjectTypeDefinition :
    *   Description?
    *   type Name ImplementsInterfaces? Directives[Const]? FieldsDefinition?
+   *
+   * @internal
    */
 
   parseObjectTypeDefinition() {
@@ -827,6 +961,8 @@ export class Parser {
    * ImplementsInterfaces :
    *   - implements `&`? NamedType
    *   - ImplementsInterfaces & NamedType
+   *
+   * @internal
    */
 
   parseImplementsInterfaces() {
@@ -838,6 +974,8 @@ export class Parser {
    * ```
    * FieldsDefinition : { FieldDefinition+ }
    * ```
+   *
+   * @internal
    */
 
   parseFieldsDefinition() {
@@ -850,6 +988,8 @@ export class Parser {
   /**
    * FieldDefinition :
    *   - Description? Name ArgumentsDefinition? : Type Directives[Const]?
+   *
+   * @internal
    */
 
   parseFieldDefinition() {
@@ -871,6 +1011,8 @@ export class Parser {
   }
   /**
    * ArgumentsDefinition : ( InputValueDefinition+ )
+   *
+   * @internal
    */
 
   parseArgumentDefs() {
@@ -883,6 +1025,8 @@ export class Parser {
   /**
    * InputValueDefinition :
    *   - Description? Name : Type DefaultValue? Directives[Const]?
+   *
+   * @internal
    */
 
   parseInputValueDef() {
@@ -910,6 +1054,8 @@ export class Parser {
   /**
    * InterfaceTypeDefinition :
    *   - Description? interface Name Directives[Const]? FieldsDefinition?
+   *
+   * @internal
    */
 
   parseInterfaceTypeDefinition() {
@@ -932,6 +1078,8 @@ export class Parser {
   /**
    * UnionTypeDefinition :
    *   - Description? union Name Directives[Const]? UnionMemberTypes?
+   *
+   * @internal
    */
 
   parseUnionTypeDefinition() {
@@ -953,6 +1101,8 @@ export class Parser {
    * UnionMemberTypes :
    *   - = `|`? NamedType
    *   - UnionMemberTypes | NamedType
+   *
+   * @internal
    */
 
   parseUnionMemberTypes() {
@@ -963,6 +1113,8 @@ export class Parser {
   /**
    * EnumTypeDefinition :
    *   - Description? enum Name Directives[Const]? EnumValuesDefinition?
+   *
+   * @internal
    */
 
   parseEnumTypeDefinition() {
@@ -984,6 +1136,8 @@ export class Parser {
    * ```
    * EnumValuesDefinition : { EnumValueDefinition+ }
    * ```
+   *
+   * @internal
    */
 
   parseEnumValuesDefinition() {
@@ -995,6 +1149,8 @@ export class Parser {
   }
   /**
    * EnumValueDefinition : Description? EnumValue Directives[Const]?
+   *
+   * @internal
    */
 
   parseEnumValueDefinition() {
@@ -1011,6 +1167,8 @@ export class Parser {
   }
   /**
    * EnumValue : Name but not `true`, `false` or `null`
+   *
+   * @internal
    */
 
   parseEnumValueName() {
@@ -1033,6 +1191,8 @@ export class Parser {
   /**
    * InputObjectTypeDefinition :
    *   - Description? input Name Directives[Const]? InputFieldsDefinition?
+   *
+   * @internal
    */
 
   parseInputObjectTypeDefinition() {
@@ -1054,6 +1214,8 @@ export class Parser {
    * ```
    * InputFieldsDefinition : { InputValueDefinition+ }
    * ```
+   *
+   * @internal
    */
 
   parseInputFieldsDefinition() {
@@ -1075,6 +1237,9 @@ export class Parser {
    *   - UnionTypeExtension
    *   - EnumTypeExtension
    *   - InputObjectTypeDefinition
+   *   - DirectiveDefinitionExtension
+   *
+   * @internal
    */
 
   parseTypeSystemExtension() {
@@ -1102,6 +1267,13 @@ export class Parser {
 
         case 'input':
           return this.parseInputObjectTypeExtension();
+
+        case 'directive':
+          if (this._options.experimentalDirectivesOnDirectiveDefinitions) {
+            return this.parseDirectiveDefinitionExtension();
+          }
+
+          break;
       }
     }
 
@@ -1113,6 +1285,8 @@ export class Parser {
    *  - extend schema Directives[Const]? { OperationTypeDefinition+ }
    *  - extend schema Directives[Const]
    * ```
+   *
+   * @internal
    */
 
   parseSchemaExtension() {
@@ -1139,6 +1313,8 @@ export class Parser {
   /**
    * ScalarTypeExtension :
    *   - extend scalar Name Directives[Const]
+   *
+   * @internal
    */
 
   parseScalarTypeExtension() {
@@ -1163,6 +1339,8 @@ export class Parser {
    *  - extend type Name ImplementsInterfaces? Directives[Const]? FieldsDefinition
    *  - extend type Name ImplementsInterfaces? Directives[Const]
    *  - extend type Name ImplementsInterfaces
+   *
+   * @internal
    */
 
   parseObjectTypeExtension() {
@@ -1195,6 +1373,8 @@ export class Parser {
    *  - extend interface Name ImplementsInterfaces? Directives[Const]? FieldsDefinition
    *  - extend interface Name ImplementsInterfaces? Directives[Const]
    *  - extend interface Name ImplementsInterfaces
+   *
+   * @internal
    */
 
   parseInterfaceTypeExtension() {
@@ -1226,6 +1406,8 @@ export class Parser {
    * UnionTypeExtension :
    *   - extend union Name Directives[Const]? UnionMemberTypes
    *   - extend union Name Directives[Const]
+   *
+   * @internal
    */
 
   parseUnionTypeExtension() {
@@ -1251,6 +1433,8 @@ export class Parser {
    * EnumTypeExtension :
    *   - extend enum Name Directives[Const]? EnumValuesDefinition
    *   - extend enum Name Directives[Const]
+   *
+   * @internal
    */
 
   parseEnumTypeExtension() {
@@ -1276,6 +1460,8 @@ export class Parser {
    * InputObjectTypeExtension :
    *   - extend input Name Directives[Const]? InputFieldsDefinition
    *   - extend input Name Directives[Const]
+   *
+   * @internal
    */
 
   parseInputObjectTypeExtension() {
@@ -1297,11 +1483,32 @@ export class Parser {
       fields,
     });
   }
+
+  parseDirectiveDefinitionExtension() {
+    const start = this._lexer.token;
+    this.expectKeyword('extend');
+    this.expectKeyword('directive');
+    this.expectToken(TokenKind.AT);
+    const name = this.parseName();
+    const directives = this.parseConstDirectives();
+
+    if (directives.length === 0) {
+      throw this.unexpected();
+    }
+
+    return this.node(start, {
+      kind: Kind.DIRECTIVE_EXTENSION,
+      name,
+      directives,
+    });
+  }
   /**
    * ```
    * DirectiveDefinition :
    *   - Description? directive @ Name ArgumentsDefinition? `repeatable`? on DirectiveLocations
    * ```
+   *
+   * @internal
    */
 
   parseDirectiveDefinition() {
@@ -1311,6 +1518,10 @@ export class Parser {
     this.expectToken(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();
@@ -1319,6 +1530,7 @@ export class Parser {
       description,
       name,
       arguments: args,
+      directives,
       repeatable,
       locations,
     });
@@ -1327,6 +1539,8 @@ export class Parser {
    * DirectiveLocations :
    *   - `|`? DirectiveLocation
    *   - DirectiveLocations | DirectiveLocation
+   *
+   * @internal
    */
 
   parseDirectiveLocations() {
@@ -1358,6 +1572,7 @@ export class Parser {
    *   `ENUM_VALUE`
    *   `INPUT_OBJECT`
    *   `INPUT_FIELD_DEFINITION`
+   *   `DIRECTIVE_DEFINITION`
    */
 
   parseDirectiveLocation() {
@@ -1378,6 +1593,19 @@ export 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() {
@@ -1441,6 +1669,8 @@ export 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) {
@@ -1456,6 +1686,8 @@ export class Parser {
   }
   /**
    * Determines if the next token is of a given kind
+   *
+   * @internal
    */
 
   peek(kind) {
@@ -1464,6 +1696,8 @@ export 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) {
@@ -1483,6 +1717,8 @@ export 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) {
@@ -1498,6 +1734,8 @@ export 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) {
@@ -1516,6 +1754,8 @@ export 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) {
@@ -1530,6 +1770,8 @@ export class Parser {
   }
   /**
    * Helper function for creating an error when an unexpected lexed token is encountered.
+   *
+   * @internal
    */
 
   unexpected(atToken) {
@@ -1545,6 +1787,8 @@ export 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) {
@@ -1562,6 +1806,8 @@ export 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) {
@@ -1581,6 +1827,8 @@ export 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) {
@@ -1597,6 +1845,8 @@ export 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) {
@@ -1630,6 +1880,8 @@ export class Parser {
 }
 /**
  * A helper function to describe a token as a string for debugging.
+ *
+ * @internal
  */
 
 function getTokenDesc(token) {
@@ -1638,6 +1890,8 @@ function getTokenDesc(token) {
 }
 /**
  * A helper function to describe a token kind as a string for debugging.
+ *
+ * @internal
  */
 
 function getTokenKindDesc(kind) {