graphql 16.14.0 → 16.14.1

package/language/printLocation.d.ts

@@ -1,12 +1,40 @@
+/** @category Source */
 import type { Location } from './ast';
 import type { SourceLocation } from './location';
 import type { Source } from './source';
 /**
  * Render a helpful description of the location in the GraphQL Source document.
+ * @param location - The AST location to print.
+ * @returns A formatted source excerpt with line and column information.
+ * @example
+ * ```ts
+ * import { parse, printLocation } from 'graphql/language';
+ *
+ * const document = parse('type Query { hello: String }');
+ * const location = document.definitions[0].loc;
+ *
+ * if (location) {
+ *   const printed = printLocation(location);
+ *
+ *   printed; // => 'GraphQL request:1:1\n1 | type Query { hello: String }\n  | ^'
+ * }
+ * ```
  */
 export declare function printLocation(location: Location): string;
 /**
  * Render a helpful description of the location in the GraphQL Source document.
+ * @param source - The source document that contains the location.
+ * @param sourceLocation - The 1-indexed line and column to print.
+ * @returns A formatted source excerpt with line and column information.
+ * @example
+ * ```ts
+ * import { Source, printSourceLocation } from 'graphql/language';
+ *
+ * const source = new Source('type Query { hello: String }');
+ * const printed = printSourceLocation(source, { line: 1, column: 14 });
+ *
+ * printed; // => 'GraphQL request:1:14\n1 | type Query { hello: String }\n  |              ^'
+ * ```
  */
 export declare function printSourceLocation(
   source: Source,

package/language/printLocation.js

@@ -8,8 +8,25 @@ exports.printSourceLocation = printSourceLocation;
 
 var _location = require('./location.js');
 
+/** @category Source */
+
 /**
  * Render a helpful description of the location in the GraphQL Source document.
+ * @param location - The AST location to print.
+ * @returns A formatted source excerpt with line and column information.
+ * @example
+ * ```ts
+ * import { parse, printLocation } from 'graphql/language';
+ *
+ * const document = parse('type Query { hello: String }');
+ * const location = document.definitions[0].loc;
+ *
+ * if (location) {
+ *   const printed = printLocation(location);
+ *
+ *   printed; // => 'GraphQL request:1:1\n1 | type Query { hello: String }\n  | ^'
+ * }
+ * ```
  */
 function printLocation(location) {
   return printSourceLocation(
@@ -19,6 +36,18 @@ function printLocation(location) {
 }
 /**
  * Render a helpful description of the location in the GraphQL Source document.
+ * @param source - The source document that contains the location.
+ * @param sourceLocation - The 1-indexed line and column to print.
+ * @returns A formatted source excerpt with line and column information.
+ * @example
+ * ```ts
+ * import { Source, printSourceLocation } from 'graphql/language';
+ *
+ * const source = new Source('type Query { hello: String }');
+ * const printed = printSourceLocation(source, { line: 1, column: 14 });
+ *
+ * printed; // => 'GraphQL request:1:14\n1 | type Query { hello: String }\n  |              ^'
+ * ```
  */
 
 function printSourceLocation(source, sourceLocation) {

package/language/printLocation.mjs

@@ -1,7 +1,23 @@
+/** @category Source */
 import { getLocation } from './location.mjs';
 
 /**
  * Render a helpful description of the location in the GraphQL Source document.
+ * @param location - The AST location to print.
+ * @returns A formatted source excerpt with line and column information.
+ * @example
+ * ```ts
+ * import { parse, printLocation } from 'graphql/language';
+ *
+ * const document = parse('type Query { hello: String }');
+ * const location = document.definitions[0].loc;
+ *
+ * if (location) {
+ *   const printed = printLocation(location);
+ *
+ *   printed; // => 'GraphQL request:1:1\n1 | type Query { hello: String }\n  | ^'
+ * }
+ * ```
  */
 export function printLocation(location) {
   return printSourceLocation(
@@ -11,6 +27,18 @@ export function printLocation(location) {
 }
 /**
  * Render a helpful description of the location in the GraphQL Source document.
+ * @param source - The source document that contains the location.
+ * @param sourceLocation - The 1-indexed line and column to print.
+ * @returns A formatted source excerpt with line and column information.
+ * @example
+ * ```ts
+ * import { Source, printSourceLocation } from 'graphql/language';
+ *
+ * const source = new Source('type Query { hello: String }');
+ * const printed = printSourceLocation(source, { line: 1, column: 14 });
+ *
+ * printed; // => 'GraphQL request:1:14\n1 | type Query { hello: String }\n  |              ^'
+ * ```
  */
 
 export function printSourceLocation(source, sourceLocation) {

package/language/printString.d.ts

@@ -1,5 +1,7 @@
 /**
  * Prints a string as a GraphQL StringValue literal. Replaces control characters
  * and excluded characters (" U+0022 and \\ U+005C) with escape sequences.
+ *
+ * @internal
  */
 export declare function printString(str: string): string;

package/language/printString.js

@@ -8,10 +8,14 @@ exports.printString = printString;
 /**
  * Prints a string as a GraphQL StringValue literal. Replaces control characters
  * and excluded characters (" U+0022 and \\ U+005C) with escape sequences.
+ *
+ * @internal
  */
 function printString(str) {
   return `"${str.replace(escapedRegExp, escapedReplacer)}"`;
-} // eslint-disable-next-line no-control-regex
+}
+/** @internal */
+// eslint-disable-next-line no-control-regex
 
 const escapedRegExp = /[\x00-\x1f\x22\x5c\x7f-\x9f]/g;
 

package/language/printString.mjs

@@ -1,10 +1,14 @@
 /**
  * Prints a string as a GraphQL StringValue literal. Replaces control characters
  * and excluded characters (" U+0022 and \\ U+005C) with escape sequences.
+ *
+ * @internal
  */
 export function printString(str) {
   return `"${str.replace(escapedRegExp, escapedReplacer)}"`;
-} // eslint-disable-next-line no-control-regex
+}
+/** @internal */
+// eslint-disable-next-line no-control-regex
 
 const escapedRegExp = /[\x00-\x1f\x22\x5c\x7f-\x9f]/g;
 

package/language/printer.d.ts

@@ -1,6 +1,18 @@
+/** @category Printing */
 import type { ASTNode } from './ast';
 /**
  * Converts an AST into a string, using one set of reasonable
  * formatting rules.
+ * @param ast - The GraphQL AST node to print.
+ * @returns A stable string representation of the AST.
+ * @example
+ * ```ts
+ * import { parse, print } from 'graphql';
+ *
+ * const ast = parse('{ hero { name } }');
+ * const text = print(ast);
+ *
+ * text; // => '{\n  hero {\n    name\n  }\n}'
+ * ```
  */
 export declare function print(ast: ASTNode): string;

package/language/printer.js

@@ -11,9 +11,22 @@ var _printString = require('./printString.js');
 
 var _visitor = require('./visitor.js');
 
+/** @category Printing */
+
 /**
  * Converts an AST into a string, using one set of reasonable
  * formatting rules.
+ * @param ast - The GraphQL AST node to print.
+ * @returns A stable string representation of the AST.
+ * @example
+ * ```ts
+ * import { parse, print } from 'graphql';
+ *
+ * const ast = parse('{ hero { name } }');
+ * const text = print(ast);
+ *
+ * text; // => '{\n  hero {\n    name\n  }\n}'
+ * ```
  */
 function print(ast) {
   return (0, _visitor.visit)(ast, printDocASTReducer);
@@ -342,6 +355,8 @@ const printDocASTReducer = {
 /**
  * Given maybeArray, print an empty string if it is null or empty, otherwise
  * print all items together separated by separator if provided
+ *
+ * @internal
  */
 
 function join(maybeArray, separator = '') {
@@ -357,6 +372,8 @@ function join(maybeArray, separator = '') {
 }
 /**
  * Given array, print each item on its own line, wrapped in an indented `{ }` block.
+ *
+ * @internal
  */
 
 function block(array) {
@@ -364,6 +381,8 @@ function block(array) {
 }
 /**
  * If maybeString is not null or empty, then wrap with start and end, otherwise print an empty string.
+ *
+ * @internal
  */
 
 function wrap(start, maybeString, end = '') {

package/language/printer.mjs

@@ -1,9 +1,21 @@
+/** @category Printing */
 import { printBlockString } from './blockString.mjs';
 import { printString } from './printString.mjs';
 import { visit } from './visitor.mjs';
 /**
  * Converts an AST into a string, using one set of reasonable
  * formatting rules.
+ * @param ast - The GraphQL AST node to print.
+ * @returns A stable string representation of the AST.
+ * @example
+ * ```ts
+ * import { parse, print } from 'graphql';
+ *
+ * const ast = parse('{ hero { name } }');
+ * const text = print(ast);
+ *
+ * text; // => '{\n  hero {\n    name\n  }\n}'
+ * ```
  */
 
 export function print(ast) {
@@ -330,6 +342,8 @@ const printDocASTReducer = {
 /**
  * Given maybeArray, print an empty string if it is null or empty, otherwise
  * print all items together separated by separator if provided
+ *
+ * @internal
  */
 
 function join(maybeArray, separator = '') {
@@ -345,6 +359,8 @@ function join(maybeArray, separator = '') {
 }
 /**
  * Given array, print each item on its own line, wrapped in an indented `{ }` block.
+ *
+ * @internal
  */
 
 function block(array) {
@@ -352,6 +368,8 @@ function block(array) {
 }
 /**
  * If maybeString is not null or empty, then wrap with start and end, otherwise print an empty string.
+ *
+ * @internal
  */
 
 function wrap(start, maybeString, end = '') {

package/language/schemaCoordinateLexer.d.ts

@@ -8,16 +8,14 @@ import type { Source } from './source';
  * source lexes, the final Token emitted by the lexer will be of kind
  * EOF, after which the lexer will repeatedly return the same EOF token
  * whenever called.
+ *
+ * @internal
  */
 export declare class SchemaCoordinateLexer implements LexerInterface {
   source: Source;
-  /**
-   * The previously focused non-ignored token.
-   */
+  /** The previously focused non-ignored token. */
   lastToken: Token;
-  /**
-   * The currently focused non-ignored token.
-   */
+  /** The currently focused non-ignored token. */
   token: Token;
   /**
    * The (1-indexed) line containing the current token.
@@ -33,11 +31,15 @@ export declare class SchemaCoordinateLexer implements LexerInterface {
   get [Symbol.toStringTag](): string;
   /**
    * Advances the token stream to the next non-ignored token.
+   *
+   * @internal
    */
   advance(): Token;
   /**
    * Looks ahead and returns the next non-ignored token, but does not change
    * the current Lexer token.
+   *
+   * @internal
    */
   lookahead(): Token;
 }

package/language/schemaCoordinateLexer.js

@@ -22,15 +22,13 @@ var _tokenKind = require('./tokenKind.js');
  * source lexes, the final Token emitted by the lexer will be of kind
  * EOF, after which the lexer will repeatedly return the same EOF token
  * whenever called.
+ *
+ * @internal
  */
 class SchemaCoordinateLexer {
-  /**
-   * The previously focused non-ignored token.
-   */
+  /** The previously focused non-ignored token. */
 
-  /**
-   * The currently focused non-ignored token.
-   */
+  /** The currently focused non-ignored token. */
 
   /**
    * The (1-indexed) line containing the current token.
@@ -62,6 +60,8 @@ class SchemaCoordinateLexer {
   }
   /**
    * Advances the token stream to the next non-ignored token.
+   *
+   * @internal
    */
 
   advance() {
@@ -72,6 +72,8 @@ class SchemaCoordinateLexer {
   /**
    * Looks ahead and returns the next non-ignored token, but does not change
    * the current Lexer token.
+   *
+   * @internal
    */
 
   lookahead() {
@@ -92,6 +94,8 @@ class SchemaCoordinateLexer {
 }
 /**
  * Gets the next token from the source starting at the given position.
+ *
+ * @internal
  */
 
 exports.SchemaCoordinateLexer = SchemaCoordinateLexer;

package/language/schemaCoordinateLexer.mjs

@@ -10,16 +10,14 @@ import { TokenKind } from './tokenKind.mjs';
  * source lexes, the final Token emitted by the lexer will be of kind
  * EOF, after which the lexer will repeatedly return the same EOF token
  * whenever called.
+ *
+ * @internal
  */
 
 export class SchemaCoordinateLexer {
-  /**
-   * The previously focused non-ignored token.
-   */
+  /** The previously focused non-ignored token. */
 
-  /**
-   * The currently focused non-ignored token.
-   */
+  /** The currently focused non-ignored token. */
 
   /**
    * The (1-indexed) line containing the current token.
@@ -45,6 +43,8 @@ export class SchemaCoordinateLexer {
   }
   /**
    * Advances the token stream to the next non-ignored token.
+   *
+   * @internal
    */
 
   advance() {
@@ -55,6 +55,8 @@ export class SchemaCoordinateLexer {
   /**
    * Looks ahead and returns the next non-ignored token, but does not change
    * the current Lexer token.
+   *
+   * @internal
    */
 
   lookahead() {
@@ -75,6 +77,8 @@ export class SchemaCoordinateLexer {
 }
 /**
  * Gets the next token from the source starting at the given position.
+ *
+ * @internal
  */
 
 function readNextToken(lexer, start) {

package/language/source.d.ts

@@ -1,3 +1,4 @@
+/** @category Source */
 interface Location {
   line: number;
   column: number;
@@ -10,10 +11,37 @@ interface Location {
  * The `line` and `column` properties in `locationOffset` are 1-indexed.
  */
 export declare class Source {
+  /** The GraphQL source text. */
   body: string;
+  /** Name used in diagnostics for this source, such as a file path or request name. */
   name: string;
+  /** One-indexed line and column where this source begins. */
   locationOffset: Location;
+  /**
+   * Creates a Source instance.
+   * @param body - The GraphQL source text.
+   * @param name - Name used in diagnostics for this source.
+   * @param locationOffset - One-indexed line and column where this source begins.
+   * @example
+   * ```ts
+   * import { Source } from 'graphql/language';
+   *
+   * const source = new Source(
+   *   'type Query { greeting: String }',
+   *   'schema.graphql',
+   *   { line: 10, column: 1 },
+   * );
+   *
+   * source.body; // => 'type Query { greeting: String }'
+   * source.name; // => 'schema.graphql'
+   * source.locationOffset; // => { line: 10, column: 1 }
+   * ```
+   */
   constructor(body: string, name?: string, locationOffset?: Location);
+  /**
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
+   */
   get [Symbol.toStringTag](): string;
 }
 /**

package/language/source.js

@@ -12,6 +12,8 @@ var _inspect = require('../jsutils/inspect.js');
 
 var _instanceOf = require('../jsutils/instanceOf.js');
 
+/** @category Source */
+
 /**
  * A representation of source input to GraphQL. The `name` and `locationOffset` parameters are
  * optional, but they are useful for clients who store GraphQL documents in source files.
@@ -20,6 +22,32 @@ var _instanceOf = require('../jsutils/instanceOf.js');
  * The `line` and `column` properties in `locationOffset` are 1-indexed.
  */
 class Source {
+  /** The GraphQL source text. */
+
+  /** Name used in diagnostics for this source, such as a file path or request name. */
+
+  /** One-indexed line and column where this source begins. */
+
+  /**
+   * Creates a Source instance.
+   * @param body - The GraphQL source text.
+   * @param name - Name used in diagnostics for this source.
+   * @param locationOffset - One-indexed line and column where this source begins.
+   * @example
+   * ```ts
+   * import { Source } from 'graphql/language';
+   *
+   * const source = new Source(
+   *   'type Query { greeting: String }',
+   *   'schema.graphql',
+   *   { line: 10, column: 1 },
+   * );
+   *
+   * source.body; // => 'type Query { greeting: String }'
+   * source.name; // => 'schema.graphql'
+   * source.locationOffset; // => { line: 10, column: 1 }
+   * ```
+   */
   constructor(
     body,
     name = 'GraphQL request',
@@ -47,6 +75,10 @@ class Source {
         'column in locationOffset is 1-indexed and must be positive.',
       );
   }
+  /**
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
+   */
 
   get [Symbol.toStringTag]() {
     return 'Source';

package/language/source.mjs

@@ -1,3 +1,4 @@
+/** @category Source */
 import { devAssert } from '../jsutils/devAssert.mjs';
 import { inspect } from '../jsutils/inspect.mjs';
 import { instanceOf } from '../jsutils/instanceOf.mjs';
@@ -10,6 +11,32 @@ import { instanceOf } from '../jsutils/instanceOf.mjs';
  * The `line` and `column` properties in `locationOffset` are 1-indexed.
  */
 export class Source {
+  /** The GraphQL source text. */
+
+  /** Name used in diagnostics for this source, such as a file path or request name. */
+
+  /** One-indexed line and column where this source begins. */
+
+  /**
+   * Creates a Source instance.
+   * @param body - The GraphQL source text.
+   * @param name - Name used in diagnostics for this source.
+   * @param locationOffset - One-indexed line and column where this source begins.
+   * @example
+   * ```ts
+   * import { Source } from 'graphql/language';
+   *
+   * const source = new Source(
+   *   'type Query { greeting: String }',
+   *   'schema.graphql',
+   *   { line: 10, column: 1 },
+   * );
+   *
+   * source.body; // => 'type Query { greeting: String }'
+   * source.name; // => 'schema.graphql'
+   * source.locationOffset; // => { line: 10, column: 1 }
+   * ```
+   */
   constructor(
     body,
     name = 'GraphQL request',
@@ -34,6 +61,10 @@ export class Source {
         'column in locationOffset is 1-indexed and must be positive.',
       );
   }
+  /**
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
+   */
 
   get [Symbol.toStringTag]() {
     return 'Source';

package/language/tokenKind.d.ts

@@ -1,36 +1,63 @@
+/** @category Lexing */
 /**
  * An exported enum describing the different kinds of tokens that the
  * lexer emits.
  */
 declare enum TokenKind {
+  /** Start-of-file token. */
   SOF = '<SOF>',
+  /** End-of-file token. */
   EOF = '<EOF>',
+  /** The `!` punctuation token. */
   BANG = '!',
+  /** The `$` punctuation token. */
   DOLLAR = '$',
+  /** The `&` punctuation token. */
   AMP = '&',
+  /** The `(` punctuation token. */
   PAREN_L = '(',
+  /** The `)` punctuation token. */
   PAREN_R = ')',
+  /** The `.` punctuation token. */
   DOT = '.',
+  /** The `...` spread punctuation token. */
   SPREAD = '...',
+  /** The `:` punctuation token. */
   COLON = ':',
+  /** The `=` punctuation token. */
   EQUALS = '=',
+  /** The `@` punctuation token. */
   AT = '@',
+  /** The `[` punctuation token. */
   BRACKET_L = '[',
+  /** The `]` punctuation token. */
   BRACKET_R = ']',
+  /** The `{` punctuation token. */
   BRACE_L = '{',
+  /** The `|` punctuation token. */
   PIPE = '|',
+  /** The `}` punctuation token. */
   BRACE_R = '}',
+  /** A GraphQL name token or name AST node. */
   NAME = 'Name',
+  /** An integer value token or AST node. */
   INT = 'Int',
+  /** A floating-point value token or AST node. */
   FLOAT = 'Float',
+  /** A string value token or AST node. */
   STRING = 'String',
+  /** A block string value token. */
   BLOCK_STRING = 'BlockString',
+  /** A comment token. */
   COMMENT = 'Comment',
 }
 export { TokenKind };
 /**
- * The enum type representing the token kinds values.
- *
- * @deprecated Please use `TokenKind`. Will be remove in v17.
+ * Deprecated legacy alias for the enum type representing token kind values.
+ * This alias will be removed in v17. In v17, `TokenKind` 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 `TokenKind` as both the
+ * runtime value and the type.
  */
 export declare type TokenKindEnum = typeof TokenKind;

package/language/tokenKind.js

@@ -5,6 +5,8 @@ Object.defineProperty(exports, '__esModule', {
 });
 exports.TokenKind = void 0;
 
+/** @category Lexing */
+
 /**
  * An exported enum describing the different kinds of tokens that the
  * lexer emits.
@@ -38,7 +40,10 @@ exports.TokenKind = TokenKind;
   TokenKind['COMMENT'] = 'Comment';
 })(TokenKind || (exports.TokenKind = TokenKind = {}));
 /**
- * The enum type representing the token kinds values.
- *
- * @deprecated Please use `TokenKind`. Will be remove in v17.
+ * Deprecated legacy alias for the enum type representing token kind values.
+ * This alias will be removed in v17. In v17, `TokenKind` 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 `TokenKind` as both the
+ * runtime value and the type.
  */

package/language/tokenKind.mjs

@@ -1,3 +1,5 @@
+/** @category Lexing */
+
 /**
  * An exported enum describing the different kinds of tokens that the
  * lexer emits.
@@ -32,7 +34,10 @@ var TokenKind;
 
 export { TokenKind };
 /**
- * The enum type representing the token kinds values.
- *
- * @deprecated Please use `TokenKind`. Will be remove in v17.
+ * Deprecated legacy alias for the enum type representing token kind values.
+ * This alias will be removed in v17. In v17, `TokenKind` 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 `TokenKind` as both the
+ * runtime value and the type.
  */