graphql 16.14.0 → 16.14.1

package/error/GraphQLError.d.ts

@@ -1,10 +1,10 @@
+/** @category Errors */
 import type { Maybe } from '../jsutils/Maybe';
 import type { ASTNode } from '../language/ast';
 import type { SourceLocation } from '../language/location';
 import type { Source } from '../language/source';
 /**
  * Custom extensions
- *
  * @remarks
  * Use a unique identifier name for your extension, for example the name of
  * your library or project. Do not use a shortened identifier as this increases
@@ -16,7 +16,6 @@ export interface GraphQLErrorExtensions {
 }
 /**
  * Custom formatted extensions
- *
  * @remarks
  * Use a unique identifier name for your extension, for example the name of
  * your library or project. Do not use a shortened identifier as this increases
@@ -26,16 +25,24 @@ export interface GraphQLErrorExtensions {
 export interface GraphQLFormattedErrorExtensions {
   [attributeName: string]: unknown;
 }
+/** Options used to construct a GraphQLError. */
 export interface GraphQLErrorOptions {
+  /** AST node or nodes associated with this error. */
   nodes?: ReadonlyArray<ASTNode> | ASTNode | null;
+  /** Source document used to derive error locations. */
   source?: Maybe<Source>;
+  /** Character offsets in the source document associated with this error. */
   positions?: Maybe<ReadonlyArray<number>>;
+  /** Response path where this error occurred during execution. */
   path?: Maybe<ReadonlyArray<string | number>>;
+  /** Original error that caused this GraphQLError, if one exists. */
   originalError?: Maybe<
     Error & {
+      /** Extension fields associated with this value. */
       readonly extensions?: unknown;
     }
   >;
+  /** Extension fields to include in the formatted result. */
   extensions?: Maybe<GraphQLErrorExtensions>;
 }
 /**
@@ -63,9 +70,7 @@ export declare class GraphQLError extends Error {
    * Enumerable, and appears in the result of JSON.stringify().
    */
   readonly path: ReadonlyArray<string | number> | undefined;
-  /**
-   * An array of GraphQL AST Nodes corresponding to this error.
-   */
+  /** An array of GraphQL AST Nodes corresponding to this error. */
   readonly nodes: ReadonlyArray<ASTNode> | undefined;
   /**
    * The source GraphQL document for the first location of this error.
@@ -79,16 +84,92 @@ export declare class GraphQLError extends Error {
    * which correspond to this error.
    */
   readonly positions: ReadonlyArray<number> | undefined;
-  /**
-   * The original error thrown from a field resolver during execution.
-   */
+  /** Original error that caused this GraphQLError, if one exists. */
   readonly originalError: Error | undefined;
+  /** Extension fields to add to the formatted error. */
+  readonly extensions: GraphQLErrorExtensions;
   /**
-   * Extension fields to add to the formatted error.
+   * Creates a GraphQLError instance.
+   * @param message - Human-readable error message.
+   * @param options - Error metadata such as source locations, response path, original error, and extensions.
+   * This positional-arguments constructor overload is deprecated. Use the
+   * `GraphQLError(message, options)` overload instead.
+   * @example
+   * ```ts
+   * // Create an error from AST nodes and response metadata.
+   * import { parse } from 'graphql/language';
+   * import { GraphQLError } from 'graphql/error';
+   *
+   * const document = parse('{ greeting }');
+   * const fieldNode = document.definitions[0].selectionSet.selections[0];
+   * const error = new GraphQLError('Cannot query this field.', {
+   *   nodes: fieldNode,
+   *   path: ['greeting'],
+   *   extensions: { code: 'FORBIDDEN' },
+   * });
+   *
+   * error.message; // => 'Cannot query this field.'
+   * error.locations; // => [{ line: 1, column: 3 }]
+   * error.path; // => ['greeting']
+   * error.extensions; // => { code: 'FORBIDDEN' }
+   * ```
+   * @example
+   * ```ts
+   * // This variant derives locations from source positions and preserves the original error.
+   * import { Source } from 'graphql/language';
+   * import { GraphQLError } from 'graphql/error';
+   *
+   * const source = new Source('{ greeting }');
+   * const originalError = new Error('Database unavailable.');
+   * const error = new GraphQLError('Resolver failed.', {
+   *   source,
+   *   positions: [2],
+   *   path: ['greeting'],
+   *   originalError,
+   * });
+   *
+   * error.locations; // => [{ line: 1, column: 3 }]
+   * error.path; // => ['greeting']
+   * error.originalError; // => originalError
+   * ```
    */
-  readonly extensions: GraphQLErrorExtensions;
   constructor(message: string, options?: GraphQLErrorOptions);
   /**
+   * Creates a GraphQLError instance using the legacy positional constructor.
+   * This deprecated overload will be removed in v17. Prefer the
+   * `GraphQLErrorOptions` object overload, which keeps optional error metadata
+   * in a single options bag.
+   * @param message - Human-readable error message.
+   * @param nodes - AST node or nodes associated with this error.
+   * @param source - Source document used to derive error locations.
+   * @param positions - Character offsets in the source document associated with
+   * this error.
+   * @param path - Response path where this error occurred during execution.
+   * @param originalError - Original error that caused this GraphQLError, if one
+   * exists.
+   * @param extensions - Extension fields to include in the formatted error.
+   * @example
+   * ```ts
+   * import { Source } from 'graphql/language';
+   * import { GraphQLError } from 'graphql/error';
+   *
+   * const source = new Source('{ greeting }');
+   * const originalError = new Error('Database unavailable.');
+   * const error = new GraphQLError(
+   *   'Resolver failed.',
+   *   undefined,
+   *   source,
+   *   [2],
+   *   ['greeting'],
+   *   originalError,
+   *   { code: 'INTERNAL' },
+   * );
+   *
+   * error.locations; // => [{ line: 1, column: 3 }]
+   * error.path; // => ['greeting']
+   * error.originalError; // => originalError
+   * error.extensions; // => { code: 'INTERNAL' }
+   * ```
    * @deprecated Please use the `GraphQLErrorOptions` constructor overload instead.
    */
   constructor(
@@ -104,13 +185,46 @@ export declare class GraphQLError extends Error {
     >,
     extensions?: Maybe<GraphQLErrorExtensions>,
   );
+  /**
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
+   */
   get [Symbol.toStringTag](): string;
+  /**
+   * Returns this error as a human-readable message with source locations.
+   * @returns The formatted error string.
+   * @example
+   * ```ts
+   * import { Source } from 'graphql/language';
+   * import { GraphQLError } from 'graphql/error';
+   *
+   * const error = new GraphQLError('Cannot query field "name".', {
+   *   source: new Source('{ name }'),
+   *   positions: [2],
+   * });
+   *
+   * error.toString(); // => 'Cannot query field "name".\n\nGraphQL request:1:3\n1 | { name }\n  |   ^'
+   * ```
+   */
   toString(): string;
+  /**
+   * Returns the JSON representation used when this object is serialized.
+   * @returns The JSON-serializable representation.
+   * @example
+   * ```ts
+   * import { GraphQLError } from 'graphql/error';
+   *
+   * const error = new GraphQLError('Resolver failed.', {
+   *   path: ['viewer', 'name'],
+   *   extensions: { code: 'INTERNAL' },
+   * });
+   *
+   * error.toJSON(); // => { message: 'Resolver failed.', path: ['viewer', 'name'], extensions: { code: 'INTERNAL' } }
+   * ```
+   */
   toJSON(): GraphQLFormattedError;
 }
-/**
- * See: https://spec.graphql.org/draft/#sec-Errors
- */
+/** See: https://spec.graphql.org/draft/#sec-Errors */
 export interface GraphQLFormattedError {
   /**
    * A short, human-readable summary of the problem that **SHOULD NOT** change
@@ -138,15 +252,37 @@ export interface GraphQLFormattedError {
 }
 /**
  * Prints a GraphQLError to a string, representing useful location information
- * about the error's position in the source.
+ * about the error's position in the source. This deprecated helper is retained
+ * for backwards compatibility; call `error.toString()` instead because
+ * printError will be removed in v17.
+ * @param error - The error to format.
+ * @returns The printed string representation.
+ * @example
+ * ```ts
+ * import { GraphQLError, printError } from 'graphql/error';
+ *
+ * const message = printError(new GraphQLError('Example error'));
  *
+ * message; // => 'Example error'
+ * ```
  * @deprecated Please use `error.toString` instead. Will be removed in v17
  */
 export declare function printError(error: GraphQLError): string;
 /**
  * Given a GraphQLError, format it according to the rules described by the
- * Response Format, Errors section of the GraphQL Specification.
+ * Response Format, Errors section of the GraphQL Specification. This deprecated
+ * helper is retained for backwards compatibility; call `error.toJSON()`
+ * instead because formatError will be removed in v17.
+ * @param error - The error to format.
+ * @returns The JSON-serializable formatted error.
+ * @example
+ * ```ts
+ * import { GraphQLError, formatError } from 'graphql/error';
+ *
+ * const formatted = formatError(new GraphQLError('Example error'));
  *
+ * formatted; // => { message: 'Example error' }
+ * ```
  * @deprecated Please use `error.toJSON` instead. Will be removed in v17
  */
 export declare function formatError(error: GraphQLError): GraphQLFormattedError;

package/error/GraphQLError.js

@@ -13,6 +13,7 @@ var _location = require('../language/location.js');
 
 var _printLocation = require('../language/printLocation.js');
 
+/** @category Errors */
 function toNormalizedOptions(args) {
   const firstArg = args[0];
 
@@ -55,9 +56,7 @@ class GraphQLError extends Error {
    * Enumerable, and appears in the result of JSON.stringify().
    */
 
-  /**
-   * An array of GraphQL AST Nodes corresponding to this error.
-   */
+  /** An array of GraphQL AST Nodes corresponding to this error. */
 
   /**
    * The source GraphQL document for the first location of this error.
@@ -71,15 +70,92 @@ class GraphQLError extends Error {
    * which correspond to this error.
    */
 
-  /**
-   * The original error thrown from a field resolver during execution.
-   */
+  /** Original error that caused this GraphQLError, if one exists. */
+
+  /** Extension fields to add to the formatted error. */
 
   /**
-   * Extension fields to add to the formatted error.
+   * Creates a GraphQLError instance.
+   * @param message - Human-readable error message.
+   * @param options - Error metadata such as source locations, response path, original error, and extensions.
+   * This positional-arguments constructor overload is deprecated. Use the
+   * `GraphQLError(message, options)` overload instead.
+   * @example
+   * ```ts
+   * // Create an error from AST nodes and response metadata.
+   * import { parse } from 'graphql/language';
+   * import { GraphQLError } from 'graphql/error';
+   *
+   * const document = parse('{ greeting }');
+   * const fieldNode = document.definitions[0].selectionSet.selections[0];
+   * const error = new GraphQLError('Cannot query this field.', {
+   *   nodes: fieldNode,
+   *   path: ['greeting'],
+   *   extensions: { code: 'FORBIDDEN' },
+   * });
+   *
+   * error.message; // => 'Cannot query this field.'
+   * error.locations; // => [{ line: 1, column: 3 }]
+   * error.path; // => ['greeting']
+   * error.extensions; // => { code: 'FORBIDDEN' }
+   * ```
+   * @example
+   * ```ts
+   * // This variant derives locations from source positions and preserves the original error.
+   * import { Source } from 'graphql/language';
+   * import { GraphQLError } from 'graphql/error';
+   *
+   * const source = new Source('{ greeting }');
+   * const originalError = new Error('Database unavailable.');
+   * const error = new GraphQLError('Resolver failed.', {
+   *   source,
+   *   positions: [2],
+   *   path: ['greeting'],
+   *   originalError,
+   * });
+   *
+   * error.locations; // => [{ line: 1, column: 3 }]
+   * error.path; // => ['greeting']
+   * error.originalError; // => originalError
+   * ```
    */
 
   /**
+   * Creates a GraphQLError instance using the legacy positional constructor.
+   * This deprecated overload will be removed in v17. Prefer the
+   * `GraphQLErrorOptions` object overload, which keeps optional error metadata
+   * in a single options bag.
+   * @param message - Human-readable error message.
+   * @param nodes - AST node or nodes associated with this error.
+   * @param source - Source document used to derive error locations.
+   * @param positions - Character offsets in the source document associated with
+   * this error.
+   * @param path - Response path where this error occurred during execution.
+   * @param originalError - Original error that caused this GraphQLError, if one
+   * exists.
+   * @param extensions - Extension fields to include in the formatted error.
+   * @example
+   * ```ts
+   * import { Source } from 'graphql/language';
+   * import { GraphQLError } from 'graphql/error';
+   *
+   * const source = new Source('{ greeting }');
+   * const originalError = new Error('Database unavailable.');
+   * const error = new GraphQLError(
+   *   'Resolver failed.',
+   *   undefined,
+   *   source,
+   *   [2],
+   *   ['greeting'],
+   *   originalError,
+   *   { code: 'INTERNAL' },
+   * );
+   *
+   * error.locations; // => [{ line: 1, column: 3 }]
+   * error.path; // => ['greeting']
+   * error.originalError; // => originalError
+   * error.extensions; // => { code: 'INTERNAL' }
+   * ```
    * @deprecated Please use the `GraphQLErrorOptions` constructor overload instead.
    */
   constructor(message, ...rawArgs) {
@@ -191,10 +267,30 @@ class GraphQLError extends Error {
     }
     /* c8 ignore stop */
   }
+  /**
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
+   */
 
   get [Symbol.toStringTag]() {
     return 'GraphQLError';
   }
+  /**
+   * Returns this error as a human-readable message with source locations.
+   * @returns The formatted error string.
+   * @example
+   * ```ts
+   * import { Source } from 'graphql/language';
+   * import { GraphQLError } from 'graphql/error';
+   *
+   * const error = new GraphQLError('Cannot query field "name".', {
+   *   source: new Source('{ name }'),
+   *   positions: [2],
+   * });
+   *
+   * error.toString(); // => 'Cannot query field "name".\n\nGraphQL request:1:3\n1 | { name }\n  |   ^'
+   * ```
+   */
 
   toString() {
     let output = this.message;
@@ -215,6 +311,21 @@ class GraphQLError extends Error {
 
     return output;
   }
+  /**
+   * Returns the JSON representation used when this object is serialized.
+   * @returns The JSON-serializable representation.
+   * @example
+   * ```ts
+   * import { GraphQLError } from 'graphql/error';
+   *
+   * const error = new GraphQLError('Resolver failed.', {
+   *   path: ['viewer', 'name'],
+   *   extensions: { code: 'INTERNAL' },
+   * });
+   *
+   * error.toJSON(); // => { message: 'Resolver failed.', path: ['viewer', 'name'], extensions: { code: 'INTERNAL' } }
+   * ```
+   */
 
   toJSON() {
     const formattedError = {
@@ -242,14 +353,23 @@ exports.GraphQLError = GraphQLError;
 function undefinedIfEmpty(array) {
   return array === undefined || array.length === 0 ? undefined : array;
 }
-/**
- * See: https://spec.graphql.org/draft/#sec-Errors
- */
+/** See: https://spec.graphql.org/draft/#sec-Errors */
 
 /**
  * Prints a GraphQLError to a string, representing useful location information
- * about the error's position in the source.
+ * about the error's position in the source. This deprecated helper is retained
+ * for backwards compatibility; call `error.toString()` instead because
+ * printError will be removed in v17.
+ * @param error - The error to format.
+ * @returns The printed string representation.
+ * @example
+ * ```ts
+ * import { GraphQLError, printError } from 'graphql/error';
+ *
+ * const message = printError(new GraphQLError('Example error'));
  *
+ * message; // => 'Example error'
+ * ```
  * @deprecated Please use `error.toString` instead. Will be removed in v17
  */
 function printError(error) {
@@ -257,8 +377,19 @@ function printError(error) {
 }
 /**
  * Given a GraphQLError, format it according to the rules described by the
- * Response Format, Errors section of the GraphQL Specification.
+ * Response Format, Errors section of the GraphQL Specification. This deprecated
+ * helper is retained for backwards compatibility; call `error.toJSON()`
+ * instead because formatError will be removed in v17.
+ * @param error - The error to format.
+ * @returns The JSON-serializable formatted error.
+ * @example
+ * ```ts
+ * import { GraphQLError, formatError } from 'graphql/error';
+ *
+ * const formatted = formatError(new GraphQLError('Example error'));
  *
+ * formatted; // => { message: 'Example error' }
+ * ```
  * @deprecated Please use `error.toJSON` instead. Will be removed in v17
  */
 

package/error/GraphQLError.mjs

@@ -1,3 +1,4 @@
+/** @category Errors */
 import { isObjectLike } from '../jsutils/isObjectLike.mjs';
 import { getLocation } from '../language/location.mjs';
 import {
@@ -47,9 +48,7 @@ export class GraphQLError extends Error {
    * Enumerable, and appears in the result of JSON.stringify().
    */
 
-  /**
-   * An array of GraphQL AST Nodes corresponding to this error.
-   */
+  /** An array of GraphQL AST Nodes corresponding to this error. */
 
   /**
    * The source GraphQL document for the first location of this error.
@@ -63,15 +62,92 @@ export class GraphQLError extends Error {
    * which correspond to this error.
    */
 
-  /**
-   * The original error thrown from a field resolver during execution.
-   */
+  /** Original error that caused this GraphQLError, if one exists. */
+
+  /** Extension fields to add to the formatted error. */
 
   /**
-   * Extension fields to add to the formatted error.
+   * Creates a GraphQLError instance.
+   * @param message - Human-readable error message.
+   * @param options - Error metadata such as source locations, response path, original error, and extensions.
+   * This positional-arguments constructor overload is deprecated. Use the
+   * `GraphQLError(message, options)` overload instead.
+   * @example
+   * ```ts
+   * // Create an error from AST nodes and response metadata.
+   * import { parse } from 'graphql/language';
+   * import { GraphQLError } from 'graphql/error';
+   *
+   * const document = parse('{ greeting }');
+   * const fieldNode = document.definitions[0].selectionSet.selections[0];
+   * const error = new GraphQLError('Cannot query this field.', {
+   *   nodes: fieldNode,
+   *   path: ['greeting'],
+   *   extensions: { code: 'FORBIDDEN' },
+   * });
+   *
+   * error.message; // => 'Cannot query this field.'
+   * error.locations; // => [{ line: 1, column: 3 }]
+   * error.path; // => ['greeting']
+   * error.extensions; // => { code: 'FORBIDDEN' }
+   * ```
+   * @example
+   * ```ts
+   * // This variant derives locations from source positions and preserves the original error.
+   * import { Source } from 'graphql/language';
+   * import { GraphQLError } from 'graphql/error';
+   *
+   * const source = new Source('{ greeting }');
+   * const originalError = new Error('Database unavailable.');
+   * const error = new GraphQLError('Resolver failed.', {
+   *   source,
+   *   positions: [2],
+   *   path: ['greeting'],
+   *   originalError,
+   * });
+   *
+   * error.locations; // => [{ line: 1, column: 3 }]
+   * error.path; // => ['greeting']
+   * error.originalError; // => originalError
+   * ```
    */
 
   /**
+   * Creates a GraphQLError instance using the legacy positional constructor.
+   * This deprecated overload will be removed in v17. Prefer the
+   * `GraphQLErrorOptions` object overload, which keeps optional error metadata
+   * in a single options bag.
+   * @param message - Human-readable error message.
+   * @param nodes - AST node or nodes associated with this error.
+   * @param source - Source document used to derive error locations.
+   * @param positions - Character offsets in the source document associated with
+   * this error.
+   * @param path - Response path where this error occurred during execution.
+   * @param originalError - Original error that caused this GraphQLError, if one
+   * exists.
+   * @param extensions - Extension fields to include in the formatted error.
+   * @example
+   * ```ts
+   * import { Source } from 'graphql/language';
+   * import { GraphQLError } from 'graphql/error';
+   *
+   * const source = new Source('{ greeting }');
+   * const originalError = new Error('Database unavailable.');
+   * const error = new GraphQLError(
+   *   'Resolver failed.',
+   *   undefined,
+   *   source,
+   *   [2],
+   *   ['greeting'],
+   *   originalError,
+   *   { code: 'INTERNAL' },
+   * );
+   *
+   * error.locations; // => [{ line: 1, column: 3 }]
+   * error.path; // => ['greeting']
+   * error.originalError; // => originalError
+   * error.extensions; // => { code: 'INTERNAL' }
+   * ```
    * @deprecated Please use the `GraphQLErrorOptions` constructor overload instead.
    */
   constructor(message, ...rawArgs) {
@@ -181,10 +257,30 @@ export class GraphQLError extends Error {
     }
     /* c8 ignore stop */
   }
+  /**
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
+   */
 
   get [Symbol.toStringTag]() {
     return 'GraphQLError';
   }
+  /**
+   * Returns this error as a human-readable message with source locations.
+   * @returns The formatted error string.
+   * @example
+   * ```ts
+   * import { Source } from 'graphql/language';
+   * import { GraphQLError } from 'graphql/error';
+   *
+   * const error = new GraphQLError('Cannot query field "name".', {
+   *   source: new Source('{ name }'),
+   *   positions: [2],
+   * });
+   *
+   * error.toString(); // => 'Cannot query field "name".\n\nGraphQL request:1:3\n1 | { name }\n  |   ^'
+   * ```
+   */
 
   toString() {
     let output = this.message;
@@ -203,6 +299,21 @@ export class GraphQLError extends Error {
 
     return output;
   }
+  /**
+   * Returns the JSON representation used when this object is serialized.
+   * @returns The JSON-serializable representation.
+   * @example
+   * ```ts
+   * import { GraphQLError } from 'graphql/error';
+   *
+   * const error = new GraphQLError('Resolver failed.', {
+   *   path: ['viewer', 'name'],
+   *   extensions: { code: 'INTERNAL' },
+   * });
+   *
+   * error.toJSON(); // => { message: 'Resolver failed.', path: ['viewer', 'name'], extensions: { code: 'INTERNAL' } }
+   * ```
+   */
 
   toJSON() {
     const formattedError = {
@@ -228,14 +339,23 @@ export class GraphQLError extends Error {
 function undefinedIfEmpty(array) {
   return array === undefined || array.length === 0 ? undefined : array;
 }
-/**
- * See: https://spec.graphql.org/draft/#sec-Errors
- */
+/** See: https://spec.graphql.org/draft/#sec-Errors */
 
 /**
  * Prints a GraphQLError to a string, representing useful location information
- * about the error's position in the source.
+ * about the error's position in the source. This deprecated helper is retained
+ * for backwards compatibility; call `error.toString()` instead because
+ * printError will be removed in v17.
+ * @param error - The error to format.
+ * @returns The printed string representation.
+ * @example
+ * ```ts
+ * import { GraphQLError, printError } from 'graphql/error';
+ *
+ * const message = printError(new GraphQLError('Example error'));
  *
+ * message; // => 'Example error'
+ * ```
  * @deprecated Please use `error.toString` instead. Will be removed in v17
  */
 export function printError(error) {
@@ -243,8 +363,19 @@ export function printError(error) {
 }
 /**
  * Given a GraphQLError, format it according to the rules described by the
- * Response Format, Errors section of the GraphQL Specification.
+ * Response Format, Errors section of the GraphQL Specification. This deprecated
+ * helper is retained for backwards compatibility; call `error.toJSON()`
+ * instead because formatError will be removed in v17.
+ * @param error - The error to format.
+ * @returns The JSON-serializable formatted error.
+ * @example
+ * ```ts
+ * import { GraphQLError, formatError } from 'graphql/error';
+ *
+ * const formatted = formatError(new GraphQLError('Example error'));
  *
+ * formatted; // => { message: 'Example error' }
+ * ```
  * @deprecated Please use `error.toJSON` instead. Will be removed in v17
  */
 

package/error/index.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Create, format, and locate GraphQL errors.
+ *
+ * These exports are also available from the root `graphql` package.
+ * @packageDocumentation
+ */
 export { GraphQLError, printError, formatError } from './GraphQLError';
 export type {
   GraphQLErrorOptions,

package/error/index.mjs

@@ -1,3 +1,9 @@
+/**
+ * Create, format, and locate GraphQL errors.
+ *
+ * These exports are also available from the root `graphql` package.
+ * @packageDocumentation
+ */
 export { GraphQLError, printError, formatError } from './GraphQLError.mjs';
 export { syntaxError } from './syntaxError.mjs';
 export { locatedError } from './locatedError.mjs';