graphql 16.14.0 → 16.14.1

package/language/kinds.d.ts

@@ -1,73 +1,112 @@
-/**
- * The set of allowed kind values for AST nodes.
- */
+/** @category Kinds */
+/** The set of allowed kind values for AST nodes. */
 declare enum Kind {
-  /** Name */
+  /** AST kind for name nodes. */
   NAME = 'Name',
-  /** Document */
+  /** AST kind for document nodes. */
   DOCUMENT = 'Document',
+  /** AST kind for operation definition nodes. */
   OPERATION_DEFINITION = 'OperationDefinition',
+  /** AST kind for variable definition nodes. */
   VARIABLE_DEFINITION = 'VariableDefinition',
+  /** AST kind for selection set nodes. */
   SELECTION_SET = 'SelectionSet',
+  /** AST kind for field selection nodes. */
   FIELD = 'Field',
+  /** AST kind for argument nodes. */
   ARGUMENT = 'Argument',
-  /** Fragments */
+  /** AST kind for fragment spread nodes. */
   FRAGMENT_SPREAD = 'FragmentSpread',
+  /** AST kind for inline fragment nodes. */
   INLINE_FRAGMENT = 'InlineFragment',
+  /** AST kind for fragment definition nodes. */
   FRAGMENT_DEFINITION = 'FragmentDefinition',
-  /** Values */
+  /** AST kind for variable reference nodes. */
   VARIABLE = 'Variable',
+  /** AST kind for integer value nodes. */
   INT = 'IntValue',
+  /** AST kind for floating-point value nodes. */
   FLOAT = 'FloatValue',
+  /** AST kind for string value nodes. */
   STRING = 'StringValue',
+  /** AST kind for boolean value nodes. */
   BOOLEAN = 'BooleanValue',
+  /** AST kind for null value nodes. */
   NULL = 'NullValue',
+  /** AST kind for enum value nodes. */
   ENUM = 'EnumValue',
+  /** AST kind for list value nodes. */
   LIST = 'ListValue',
+  /** AST kind for object value nodes. */
   OBJECT = 'ObjectValue',
+  /** AST kind for object field nodes. */
   OBJECT_FIELD = 'ObjectField',
-  /** Directives */
+  /** AST kind for directive nodes. */
   DIRECTIVE = 'Directive',
-  /** Types */
+  /** AST kind for named type reference nodes. */
   NAMED_TYPE = 'NamedType',
+  /** AST kind for list type reference nodes. */
   LIST_TYPE = 'ListType',
+  /** AST kind for non-null type reference nodes. */
   NON_NULL_TYPE = 'NonNullType',
-  /** Type System Definitions */
+  /** AST kind for schema definition nodes. */
   SCHEMA_DEFINITION = 'SchemaDefinition',
+  /** AST kind for operation type definition nodes. */
   OPERATION_TYPE_DEFINITION = 'OperationTypeDefinition',
-  /** Type Definitions */
+  /** AST kind for scalar type definition nodes. */
   SCALAR_TYPE_DEFINITION = 'ScalarTypeDefinition',
+  /** AST kind for object type definition nodes. */
   OBJECT_TYPE_DEFINITION = 'ObjectTypeDefinition',
+  /** AST kind for field definition nodes. */
   FIELD_DEFINITION = 'FieldDefinition',
+  /** AST kind for input value definition nodes. */
   INPUT_VALUE_DEFINITION = 'InputValueDefinition',
+  /** AST kind for interface type definition nodes. */
   INTERFACE_TYPE_DEFINITION = 'InterfaceTypeDefinition',
+  /** AST kind for union type definition nodes. */
   UNION_TYPE_DEFINITION = 'UnionTypeDefinition',
+  /** AST kind for enum type definition nodes. */
   ENUM_TYPE_DEFINITION = 'EnumTypeDefinition',
+  /** AST kind for enum value definition nodes. */
   ENUM_VALUE_DEFINITION = 'EnumValueDefinition',
+  /** AST kind for input object type definition nodes. */
   INPUT_OBJECT_TYPE_DEFINITION = 'InputObjectTypeDefinition',
-  /** Directive Definitions */
+  /** AST kind for directive definition nodes. */
   DIRECTIVE_DEFINITION = 'DirectiveDefinition',
-  /** Type System Extensions */
+  /** AST kind for schema extension nodes. */
   SCHEMA_EXTENSION = 'SchemaExtension',
+  /** AST kind for directive extension nodes. */
   DIRECTIVE_EXTENSION = 'DirectiveExtension',
-  /** Type Extensions */
+  /** AST kind for scalar type extension nodes. */
   SCALAR_TYPE_EXTENSION = 'ScalarTypeExtension',
+  /** AST kind for object type extension nodes. */
   OBJECT_TYPE_EXTENSION = 'ObjectTypeExtension',
+  /** AST kind for interface type extension nodes. */
   INTERFACE_TYPE_EXTENSION = 'InterfaceTypeExtension',
+  /** AST kind for union type extension nodes. */
   UNION_TYPE_EXTENSION = 'UnionTypeExtension',
+  /** AST kind for enum type extension nodes. */
   ENUM_TYPE_EXTENSION = 'EnumTypeExtension',
+  /** AST kind for input object type extension nodes. */
   INPUT_OBJECT_TYPE_EXTENSION = 'InputObjectTypeExtension',
-  /** Schema Coordinates */
+  /** AST kind for type coordinate nodes. */
   TYPE_COORDINATE = 'TypeCoordinate',
+  /** AST kind for member coordinate nodes. */
   MEMBER_COORDINATE = 'MemberCoordinate',
+  /** AST kind for argument coordinate nodes. */
   ARGUMENT_COORDINATE = 'ArgumentCoordinate',
+  /** AST kind for directive coordinate nodes. */
   DIRECTIVE_COORDINATE = 'DirectiveCoordinate',
+  /** AST kind for directive argument coordinate nodes. */
   DIRECTIVE_ARGUMENT_COORDINATE = 'DirectiveArgumentCoordinate',
 }
 export { Kind };
 /**
- * The enum type representing the possible kind values of AST nodes.
- *
- * @deprecated Please use `Kind`. Will be remove in v17.
+ * Deprecated legacy alias for the enum type representing the possible kind
+ * values of AST nodes. This alias will be removed in v17. In v17, `Kind` is
+ * exported as the single public symbol for both the runtime object and the
+ * corresponding TypeScript type.
+ * @deprecated Will be removed in v17. In v17, use `Kind` as both the runtime
+ * value and the type.
  */
 export declare type KindEnum = typeof Kind;

package/language/kinds.js

@@ -5,9 +5,9 @@ Object.defineProperty(exports, '__esModule', {
 });
 exports.Kind = void 0;
 
-/**
- * The set of allowed kind values for AST nodes.
- */
+/** @category Kinds */
+
+/** The set of allowed kind values for AST nodes. */
 var Kind;
 exports.Kind = Kind;
 
@@ -63,7 +63,10 @@ exports.Kind = Kind;
   Kind['DIRECTIVE_ARGUMENT_COORDINATE'] = 'DirectiveArgumentCoordinate';
 })(Kind || (exports.Kind = Kind = {}));
 /**
- * The enum type representing the possible kind values of AST nodes.
- *
- * @deprecated Please use `Kind`. Will be remove in v17.
+ * Deprecated legacy alias for the enum type representing the possible kind
+ * values of AST nodes. This alias will be removed in v17. In v17, `Kind` is
+ * exported as the single public symbol for both the runtime object and the
+ * corresponding TypeScript type.
+ * @deprecated Will be removed in v17. In v17, use `Kind` as both the runtime
+ * value and the type.
  */

package/language/kinds.mjs

@@ -1,6 +1,6 @@
-/**
- * The set of allowed kind values for AST nodes.
- */
+/** @category Kinds */
+
+/** The set of allowed kind values for AST nodes. */
 var Kind;
 
 (function (Kind) {
@@ -57,7 +57,10 @@ var Kind;
 
 export { Kind };
 /**
- * The enum type representing the possible kind values of AST nodes.
- *
- * @deprecated Please use `Kind`. Will be remove in v17.
+ * Deprecated legacy alias for the enum type representing the possible kind
+ * values of AST nodes. This alias will be removed in v17. In v17, `Kind` is
+ * exported as the single public symbol for both the runtime object and the
+ * corresponding TypeScript type.
+ * @deprecated Will be removed in v17. In v17, use `Kind` as both the runtime
+ * value and the type.
  */

package/language/lexer.d.ts

@@ -1,3 +1,4 @@
+/** @category Lexing */
 import { Token } from './ast';
 import type { Source } from './source';
 import { TokenKind } from './tokenKind';
@@ -25,38 +26,70 @@ export interface LexerInterface {
  * whenever called.
  */
 export declare class Lexer implements LexerInterface {
+  /** Source document used to derive error locations. */
   source: Source;
-  /**
-   * The previously focused non-ignored token.
-   */
+  /** Most recent non-ignored token returned by the lexer. */
   lastToken: Token;
-  /**
-   * The currently focused non-ignored token.
-   */
+  /** Current non-ignored token at the lexer cursor. */
   token: Token;
-  /**
-   * The (1-indexed) line containing the current token.
-   */
+  /** The (1-indexed) line containing the current token. */
   line: number;
+  /** Character offset where the current line starts. */
+  lineStart: number;
   /**
-   * The character offset at which the current line begins.
+   * Creates a Lexer instance.
+   * @param source - Source document used to derive error locations.
+   * @example
+   * ```ts
+   * import { Lexer, Source, TokenKind } from 'graphql/language';
+   *
+   * const lexer = new Lexer(new Source('{ hello }'));
+   *
+   * lexer.token.kind; // => TokenKind.SOF
+   * lexer.advance().kind; // => TokenKind.BRACE_L
+   * lexer.advance().value; // => 'hello'
+   * lexer.advance().kind; // => TokenKind.BRACE_R
+   * ```
    */
-  lineStart: number;
   constructor(source: Source);
+  /**
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
+   */
   get [Symbol.toStringTag](): string;
   /**
    * Advances the token stream to the next non-ignored token.
+   * @returns The next non-ignored token.
+   * @example
+   * ```ts
+   * import { Lexer, Source } from 'graphql/language';
+   *
+   * const lexer = new Lexer(new Source('{ hello }'));
+   * const token = lexer.advance();
+   *
+   * token.kind; // => '{'
+   * lexer.token; // => token
+   * ```
    */
   advance(): Token;
   /**
    * Looks ahead and returns the next non-ignored token, but does not change
    * the state of Lexer.
+   * @returns The next non-ignored token without advancing the lexer.
+   * @example
+   * ```ts
+   * import { Lexer, Source } from 'graphql/language';
+   *
+   * const lexer = new Lexer(new Source('{ hello }'));
+   * const token = lexer.lookahead();
+   *
+   * token.kind; // => '{'
+   * lexer.token.kind; // => '<SOF>'
+   * ```
    */
   lookahead(): Token;
 }
-/**
- * @internal
- */
+/** @internal */
 export declare function isPunctuatorTokenKind(kind: TokenKind): boolean;
 /**
  * Prints the code point (or end of file reference) at a given location in a

package/language/lexer.js

@@ -19,6 +19,8 @@ var _characterClasses = require('./characterClasses.js');
 
 var _tokenKind = require('./tokenKind.js');
 
+/** @category Lexing */
+
 /**
  * Given a Source object, creates a Lexer for that source.
  * A Lexer is a stateful stream generator in that every time
@@ -28,20 +30,30 @@ var _tokenKind = require('./tokenKind.js');
  * whenever called.
  */
 class Lexer {
-  /**
-   * The previously focused non-ignored token.
-   */
+  /** Source document used to derive error locations. */
 
-  /**
-   * The currently focused non-ignored token.
-   */
+  /** Most recent non-ignored token returned by the lexer. */
 
-  /**
-   * The (1-indexed) line containing the current token.
-   */
+  /** Current non-ignored token at the lexer cursor. */
+
+  /** The (1-indexed) line containing the current token. */
+
+  /** Character offset where the current line starts. */
 
   /**
-   * The character offset at which the current line begins.
+   * Creates a Lexer instance.
+   * @param source - Source document used to derive error locations.
+   * @example
+   * ```ts
+   * import { Lexer, Source, TokenKind } from 'graphql/language';
+   *
+   * const lexer = new Lexer(new Source('{ hello }'));
+   *
+   * lexer.token.kind; // => TokenKind.SOF
+   * lexer.advance().kind; // => TokenKind.BRACE_L
+   * lexer.advance().value; // => 'hello'
+   * lexer.advance().kind; // => TokenKind.BRACE_R
+   * ```
    */
   constructor(source) {
     const startOfFileToken = new _ast.Token(
@@ -57,12 +69,27 @@ class Lexer {
     this.line = 1;
     this.lineStart = 0;
   }
+  /**
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
+   */
 
   get [Symbol.toStringTag]() {
     return 'Lexer';
   }
   /**
    * Advances the token stream to the next non-ignored token.
+   * @returns The next non-ignored token.
+   * @example
+   * ```ts
+   * import { Lexer, Source } from 'graphql/language';
+   *
+   * const lexer = new Lexer(new Source('{ hello }'));
+   * const token = lexer.advance();
+   *
+   * token.kind; // => '{'
+   * lexer.token; // => token
+   * ```
    */
 
   advance() {
@@ -73,6 +100,17 @@ class Lexer {
   /**
    * Looks ahead and returns the next non-ignored token, but does not change
    * the state of Lexer.
+   * @returns The next non-ignored token without advancing the lexer.
+   * @example
+   * ```ts
+   * import { Lexer, Source } from 'graphql/language';
+   *
+   * const lexer = new Lexer(new Source('{ hello }'));
+   * const token = lexer.lookahead();
+   *
+   * token.kind; // => '{'
+   * lexer.token.kind; // => '<SOF>'
+   * ```
    */
 
   lookahead() {
@@ -97,9 +135,7 @@ class Lexer {
     return token;
   }
 }
-/**
- * @internal
- */
+/** @internal */
 
 exports.Lexer = Lexer;
 
@@ -129,6 +165,8 @@ function isPunctuatorTokenKind(kind) {
  *
  * SourceCharacter ::
  *   - "Any Unicode scalar value"
+ *
+ * @internal
  */
 
 function isUnicodeScalarValue(code) {
@@ -143,6 +181,8 @@ function isUnicodeScalarValue(code) {
  * include surrogates. A surrogate pair is a valid source character as it
  * encodes a supplementary code point (above U+FFFF), but unpaired surrogate
  * code points are not valid source characters.
+ *
+ * @internal
  */
 
 function isSupplementaryCodePoint(body, location) {
@@ -199,6 +239,8 @@ function createToken(lexer, kind, start, end, value) {
  * This skips over whitespace until it finds the next lexable token, then lexes
  * punctuators immediately or calls the appropriate helper function for more
  * complicated tokens.
+ *
+ * @internal
  */
 
 function readNextToken(lexer, start) {
@@ -446,6 +488,8 @@ function readNextToken(lexer, start) {
  *
  * CommentChar :: SourceCharacter but not LineTerminator
  * ```
+ *
+ * @internal
  */
 
 function readComment(lexer, start) {
@@ -505,6 +549,8 @@ function readComment(lexer, start) {
  *
  * Sign :: one of + -
  * ```
+ *
+ * @internal
  */
 
 function readNumber(lexer, start, firstCode) {
@@ -575,6 +621,8 @@ function readNumber(lexer, start, firstCode) {
 }
 /**
  * Returns the new position in the source after reading one or more digits.
+ *
+ * @internal
  */
 
 function readDigits(lexer, start, firstCode) {
@@ -617,6 +665,8 @@ function readDigits(lexer, start, firstCode) {
  *
  * EscapedCharacter :: one of `"` `\` `/` `b` `f` `n` `r` `t`
  * ```
+ *
+ * @internal
  */
 
 function readString(lexer, start) {
@@ -765,6 +815,8 @@ function readEscapedUnicodeFixedWidth(lexer, position) {
  * will return 57005.
  *
  * Returns a negative number if any char was not a valid hexadecimal digit.
+ *
+ * @internal
  */
 
 function read16BitHexCode(body, position) {
@@ -790,6 +842,8 @@ function read16BitHexCode(body, position) {
  *   - `0` `1` `2` `3` `4` `5` `6` `7` `8` `9`
  *   - `A` `B` `C` `D` `E` `F`
  *   - `a` `b` `c` `d` `e` `f`
+ *
+ * @internal
  */
 
 function readHexDigit(code) {
@@ -812,6 +866,8 @@ function readHexDigit(code) {
  * | `n`               | U+000A     | line feed (new line)         |
  * | `r`               | U+000D     | carriage return              |
  * | `t`               | U+0009     | horizontal tab               |
+ *
+ * @internal
  */
 
 function readEscapedCharacter(lexer, position) {
@@ -896,6 +952,8 @@ function readEscapedCharacter(lexer, position) {
  *   - SourceCharacter but not `"""` or `\"""`
  *   - `\"""`
  * ```
+ *
+ * @internal
  */
 
 function readBlockString(lexer, start) {

package/language/lexer.mjs

@@ -1,3 +1,4 @@
+/** @category Lexing */
 import { syntaxError } from '../error/syntaxError.mjs';
 import { Token } from './ast.mjs';
 import { dedentBlockStringLines } from './blockString.mjs';
@@ -19,20 +20,30 @@ import { TokenKind } from './tokenKind.mjs';
  * whenever called.
  */
 export class Lexer {
-  /**
-   * The previously focused non-ignored token.
-   */
+  /** Source document used to derive error locations. */
 
-  /**
-   * The currently focused non-ignored token.
-   */
+  /** Most recent non-ignored token returned by the lexer. */
 
-  /**
-   * The (1-indexed) line containing the current token.
-   */
+  /** Current non-ignored token at the lexer cursor. */
+
+  /** The (1-indexed) line containing the current token. */
+
+  /** Character offset where the current line starts. */
 
   /**
-   * The character offset at which the current line begins.
+   * Creates a Lexer instance.
+   * @param source - Source document used to derive error locations.
+   * @example
+   * ```ts
+   * import { Lexer, Source, TokenKind } from 'graphql/language';
+   *
+   * const lexer = new Lexer(new Source('{ hello }'));
+   *
+   * lexer.token.kind; // => TokenKind.SOF
+   * lexer.advance().kind; // => TokenKind.BRACE_L
+   * lexer.advance().value; // => 'hello'
+   * lexer.advance().kind; // => TokenKind.BRACE_R
+   * ```
    */
   constructor(source) {
     const startOfFileToken = new Token(TokenKind.SOF, 0, 0, 0, 0);
@@ -42,12 +53,27 @@ export class Lexer {
     this.line = 1;
     this.lineStart = 0;
   }
+  /**
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
+   */
 
   get [Symbol.toStringTag]() {
     return 'Lexer';
   }
   /**
    * Advances the token stream to the next non-ignored token.
+   * @returns The next non-ignored token.
+   * @example
+   * ```ts
+   * import { Lexer, Source } from 'graphql/language';
+   *
+   * const lexer = new Lexer(new Source('{ hello }'));
+   * const token = lexer.advance();
+   *
+   * token.kind; // => '{'
+   * lexer.token; // => token
+   * ```
    */
 
   advance() {
@@ -58,6 +84,17 @@ export class Lexer {
   /**
    * Looks ahead and returns the next non-ignored token, but does not change
    * the state of Lexer.
+   * @returns The next non-ignored token without advancing the lexer.
+   * @example
+   * ```ts
+   * import { Lexer, Source } from 'graphql/language';
+   *
+   * const lexer = new Lexer(new Source('{ hello }'));
+   * const token = lexer.lookahead();
+   *
+   * token.kind; // => '{'
+   * lexer.token.kind; // => '<SOF>'
+   * ```
    */
 
   lookahead() {
@@ -82,9 +119,7 @@ export class Lexer {
     return token;
   }
 }
-/**
- * @internal
- */
+/** @internal */
 
 export function isPunctuatorTokenKind(kind) {
   return (
@@ -112,6 +147,8 @@ export function isPunctuatorTokenKind(kind) {
  *
  * SourceCharacter ::
  *   - "Any Unicode scalar value"
+ *
+ * @internal
  */
 
 function isUnicodeScalarValue(code) {
@@ -126,6 +163,8 @@ function isUnicodeScalarValue(code) {
  * include surrogates. A surrogate pair is a valid source character as it
  * encodes a supplementary code point (above U+FFFF), but unpaired surrogate
  * code points are not valid source characters.
+ *
+ * @internal
  */
 
 function isSupplementaryCodePoint(body, location) {
@@ -182,6 +221,8 @@ export function createToken(lexer, kind, start, end, value) {
  * This skips over whitespace until it finds the next lexable token, then lexes
  * punctuators immediately or calls the appropriate helper function for more
  * complicated tokens.
+ *
+ * @internal
  */
 
 function readNextToken(lexer, start) {
@@ -359,6 +400,8 @@ function readNextToken(lexer, start) {
  *
  * CommentChar :: SourceCharacter but not LineTerminator
  * ```
+ *
+ * @internal
  */
 
 function readComment(lexer, start) {
@@ -418,6 +461,8 @@ function readComment(lexer, start) {
  *
  * Sign :: one of + -
  * ```
+ *
+ * @internal
  */
 
 function readNumber(lexer, start, firstCode) {
@@ -488,6 +533,8 @@ function readNumber(lexer, start, firstCode) {
 }
 /**
  * Returns the new position in the source after reading one or more digits.
+ *
+ * @internal
  */
 
 function readDigits(lexer, start, firstCode) {
@@ -530,6 +577,8 @@ function readDigits(lexer, start, firstCode) {
  *
  * EscapedCharacter :: one of `"` `\` `/` `b` `f` `n` `r` `t`
  * ```
+ *
+ * @internal
  */
 
 function readString(lexer, start) {
@@ -668,6 +717,8 @@ function readEscapedUnicodeFixedWidth(lexer, position) {
  * will return 57005.
  *
  * Returns a negative number if any char was not a valid hexadecimal digit.
+ *
+ * @internal
  */
 
 function read16BitHexCode(body, position) {
@@ -693,6 +744,8 @@ function read16BitHexCode(body, position) {
  *   - `0` `1` `2` `3` `4` `5` `6` `7` `8` `9`
  *   - `A` `B` `C` `D` `E` `F`
  *   - `a` `b` `c` `d` `e` `f`
+ *
+ * @internal
  */
 
 function readHexDigit(code) {
@@ -715,6 +768,8 @@ function readHexDigit(code) {
  * | `n`               | U+000A     | line feed (new line)         |
  * | `r`               | U+000D     | carriage return              |
  * | `t`               | U+0009     | horizontal tab               |
+ *
+ * @internal
  */
 
 function readEscapedCharacter(lexer, position) {
@@ -799,6 +854,8 @@ function readEscapedCharacter(lexer, position) {
  *   - SourceCharacter but not `"""` or `\"""`
  *   - `\"""`
  * ```
+ *
+ * @internal
  */
 
 function readBlockString(lexer, start) {