graphql 16.13.2 → 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);
@@ -240,13 +253,21 @@ const printDocASTReducer = {
       join(['input', name, join(directives, ' '), block(fields)], ' '),
   },
   DirectiveDefinition: {
-    leave: ({ description, name, arguments: args, repeatable, locations }) =>
+    leave: ({
+      description,
+      name,
+      arguments: args,
+      directives,
+      repeatable,
+      locations,
+    }) =>
       wrap('', description, '\n') +
       'directive @' +
       name +
       (hasMultilineItems(args)
         ? wrap('(\n', indent(join(args, '\n')), '\n)')
         : wrap('(', join(args, ', '), ')')) +
+      wrap(' ', join(directives, ' ')) +
       (repeatable ? ' repeatable' : '') +
       ' on ' +
       join(locations, ' | '),
@@ -308,6 +329,10 @@ const printDocASTReducer = {
     leave: ({ name, directives, fields }) =>
       join(['extend input', name, join(directives, ' '), block(fields)], ' '),
   },
+  DirectiveExtension: {
+    leave: ({ name, directives }) =>
+      join(['extend directive @' + name, join(directives, ' ')], ' '),
+  },
   // Schema Coordinates
   TypeCoordinate: {
     leave: ({ name }) => name,
@@ -330,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 = '') {
@@ -345,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) {
@@ -352,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) {
@@ -228,13 +240,21 @@ const printDocASTReducer = {
       join(['input', name, join(directives, ' '), block(fields)], ' '),
   },
   DirectiveDefinition: {
-    leave: ({ description, name, arguments: args, repeatable, locations }) =>
+    leave: ({
+      description,
+      name,
+      arguments: args,
+      directives,
+      repeatable,
+      locations,
+    }) =>
       wrap('', description, '\n') +
       'directive @' +
       name +
       (hasMultilineItems(args)
         ? wrap('(\n', indent(join(args, '\n')), '\n)')
         : wrap('(', join(args, ', '), ')')) +
+      wrap(' ', join(directives, ' ')) +
       (repeatable ? ' repeatable' : '') +
       ' on ' +
       join(locations, ' | '),
@@ -296,6 +316,10 @@ const printDocASTReducer = {
     leave: ({ name, directives, fields }) =>
       join(['extend input', name, join(directives, ' '), block(fields)], ' '),
   },
+  DirectiveExtension: {
+    leave: ({ name, directives }) =>
+      join(['extend directive @' + name, join(directives, ' ')], ' '),
+  },
   // Schema Coordinates
   TypeCoordinate: {
     leave: ({ name }) => name,
@@ -318,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 = '') {
@@ -333,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) {
@@ -340,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';