graphql 17.0.0-beta.0 → 17.0.0-beta.2

package/execution/mapAsyncIterable.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"mapAsyncIterable.js","sourceRoot":"","sources":["../../src/execution/mapAsyncIterable.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,iCAAgC;AAGpD,OAAO,EAAE,yBAAyB,EAAE,wCAAuC;AAE3E;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC9B,QAA8C,EAC9C,QAAyC;IAEzC,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC;IAClD,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IACjD,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IAE/C,MAAM,QAAQ,GAAG,QAAQ;QACvB,CAAC,CAAC,GAAG,EAAE,CAAC,kBAAkB,CAAC,QAAQ,CAAC;QACpC,CAAC,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;IAE5B,MAAM,OAAO,GAAG,OAAO;QACrB,CAAC,CAAC,CAAC,MAAgB,EAAE,EAAE,CAAC,kBAAkB,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACjE,CAAC,CAAC,QAAQ,CAAC;IAEb,OAAO,yBAAyB,CAC9B,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,CAAC,EACxC,QAAQ,EACR,OAAO,CACR,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,kBAAkB,CAAC,EAA0B;IAC1D,IAAI,CAAC;QACH,MAAM,EAAE,EAAE,CAAC;IACb,CAAC;IAAC,MAAM,CAAC;QACP,eAAe;IACjB,CAAC;AACH,CAAC;AAED,KAAK,SAAS,CAAC,CAAC,oBAAoB,CAClC,QAAuD,EACvD,KAAsC;IAEtC,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;QACnC,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;QAC5B,IAAI,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;YACtB,MAAM,MAAM,MAAM,CAAC;YACnB,SAAS;QACX,CAAC;QACD,MAAM,MAAM,CAAC;IACf,CAAC;AACH,CAAC","sourcesContent":["import { isPromise } from '../jsutils/isPromise.js';\nimport type { PromiseOrValue } from '../jsutils/PromiseOrValue.js';\n\nimport { withConcurrentAbruptClose } from './withConcurrentAbruptClose.js';\n\n/**\n * Given an AsyncIterable and a callback function, return an AsyncIterator\n * which produces values mapped via calling the callback function.\n */\nexport function mapAsyncIterable<T, U>(\n  iterable: AsyncGenerator<T> | AsyncIterable<T>,\n  callback: (value: T) => PromiseOrValue<U>,\n): AsyncGenerator<U, void, void> {\n  const iterator = iterable[Symbol.asyncIterator]();\n  const returnFn = iterator.return?.bind(iterator);\n  const throwFn = iterator.throw?.bind(iterator);\n\n  const onReturn = returnFn\n    ? () => callIgnoringErrors(returnFn)\n    : () => Promise.resolve();\n\n  const onThrow = throwFn\n    ? (reason?: unknown) => callIgnoringErrors(() => throwFn(reason))\n    : onReturn;\n\n  return withConcurrentAbruptClose(\n    mapAsyncIterableImpl(iterable, callback),\n    onReturn,\n    onThrow,\n  );\n}\n\nasync function callIgnoringErrors(fn: () => Promise<unknown>): Promise<void> {\n  try {\n    await fn();\n  } catch {\n    // ignore error\n  }\n}\n\nasync function* mapAsyncIterableImpl<T, U, R = undefined>(\n  iterable: AsyncGenerator<T, R, void> | AsyncIterable<T>,\n  mapFn: (value: T) => PromiseOrValue<U>,\n): AsyncGenerator<U, void, void> {\n  for await (const value of iterable) {\n    const result = mapFn(value);\n    if (isPromise(result)) {\n      yield await result;\n      continue;\n    }\n    yield result;\n  }\n}\n"]}
+{"version":3,"file":"mapAsyncIterable.js","sourceRoot":"","sources":["../../src/execution/mapAsyncIterable.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,iCAAgC;AAGpD,OAAO,EAAE,yBAAyB,EAAE,wCAAuC;AAQ3E,MAAM,UAAU,gBAAgB,CAC9B,QAA8C,EAC9C,QAAyC;IAEzC,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC;IAClD,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IACjD,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IAE/C,MAAM,QAAQ,GAAG,QAAQ;QACvB,CAAC,CAAC,GAAG,EAAE,CAAC,kBAAkB,CAAC,QAAQ,CAAC;QACpC,CAAC,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;IAE5B,MAAM,OAAO,GAAG,OAAO;QACrB,CAAC,CAAC,CAAC,MAAgB,EAAE,EAAE,CAAC,kBAAkB,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACjE,CAAC,CAAC,QAAQ,CAAC;IAEb,OAAO,yBAAyB,CAC9B,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,CAAC,EACxC,QAAQ,EACR,OAAO,CACR,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,kBAAkB,CAAC,EAA0B;IAC1D,IAAI,CAAC;QACH,MAAM,EAAE,EAAE,CAAC;IACb,CAAC;IAAC,MAAM,CAAC;IAET,CAAC;AACH,CAAC;AAED,KAAK,SAAS,CAAC,CAAC,oBAAoB,CAClC,QAAuD,EACvD,KAAsC;IAEtC,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;QACnC,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;QAC5B,IAAI,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;YACtB,MAAM,MAAM,MAAM,CAAC;YACnB,SAAS;QACX,CAAC;QACD,MAAM,MAAM,CAAC;IACf,CAAC;AACH,CAAC","sourcesContent":["import { isPromise } from '../jsutils/isPromise.ts';\nimport type { PromiseOrValue } from '../jsutils/PromiseOrValue.ts';\n\nimport { withConcurrentAbruptClose } from './withConcurrentAbruptClose.ts';\n\n/**\n * Given an AsyncIterable and a callback function, return an AsyncIterator\n * which produces values mapped via calling the callback function.\n *\n * @internal\n */\nexport function mapAsyncIterable<T, U>(\n  iterable: AsyncGenerator<T> | AsyncIterable<T>,\n  callback: (value: T) => PromiseOrValue<U>,\n): AsyncGenerator<U, void, void> {\n  const iterator = iterable[Symbol.asyncIterator]();\n  const returnFn = iterator.return?.bind(iterator);\n  const throwFn = iterator.throw?.bind(iterator);\n\n  const onReturn = returnFn\n    ? () => callIgnoringErrors(returnFn)\n    : () => Promise.resolve();\n\n  const onThrow = throwFn\n    ? (reason?: unknown) => callIgnoringErrors(() => throwFn(reason))\n    : onReturn;\n\n  return withConcurrentAbruptClose(\n    mapAsyncIterableImpl(iterable, callback),\n    onReturn,\n    onThrow,\n  );\n}\n\nasync function callIgnoringErrors(fn: () => Promise<unknown>): Promise<void> {\n  try {\n    await fn();\n  } catch {\n    // ignore error\n  }\n}\n\nasync function* mapAsyncIterableImpl<T, U, R = undefined>(\n  iterable: AsyncGenerator<T, R, void> | AsyncIterable<T>,\n  mapFn: (value: T) => PromiseOrValue<U>,\n): AsyncGenerator<U, void, void> {\n  for await (const value of iterable) {\n    const result = mapFn(value);\n    if (isPromise(result)) {\n      yield await result;\n      continue;\n    }\n    yield result;\n  }\n}\n"]}

package/execution/returnIteratorCatchingErrors.d.mts

@@ -1 +1,2 @@
+/** @internal */
 export declare function returnIteratorCatchingErrors(iterator: AsyncIterator<unknown>): Promise<void>;

package/execution/returnIteratorCatchingErrors.d.ts

@@ -1 +1,2 @@
+/** @internal */
 export declare function returnIteratorCatchingErrors(iterator: AsyncIterator<unknown>): Promise<void>;

package/execution/returnIteratorCatchingErrors.js

@@ -5,8 +5,7 @@ async function returnIteratorCatchingErrors(iterator) {
     try {
         await iterator.return?.();
     }
-    catch /* c8 ignore next 2 */ {
-        // ignore errors
+    catch {
     }
 }
 //# sourceMappingURL=returnIteratorCatchingErrors.js.map

package/execution/returnIteratorCatchingErrors.js.map

@@ -1 +1 @@
-{"version":3,"file":"returnIteratorCatchingErrors.js","sourceRoot":"","sources":["../../src/execution/returnIteratorCatchingErrors.ts"],"names":[],"mappings":";;AAAA,oEAQC;AARM,KAAK,UAAU,4BAA4B,CAChD,QAAgC;IAEhC,IAAI,CAAC;QACH,MAAM,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC;IAC5B,CAAC;IAAC,MAAM,sBAAsB,CAAC,CAAC;QAC9B,gBAAgB;IAClB,CAAC;AACH,CAAC","sourcesContent":["export async function returnIteratorCatchingErrors(\n  iterator: AsyncIterator<unknown>,\n): Promise<void> {\n  try {\n    await iterator.return?.();\n  } catch /* c8 ignore next 2 */ {\n    // ignore errors\n  }\n}\n"]}
+{"version":3,"file":"returnIteratorCatchingErrors.js","sourceRoot":"","sources":["../../src/execution/returnIteratorCatchingErrors.ts"],"names":[],"mappings":";;AACA,oEAQC;AARM,KAAK,UAAU,4BAA4B,CAChD,QAAgC;IAEhC,IAAI,CAAC;QACH,MAAM,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;IAET,CAAC;AACH,CAAC","sourcesContent":["/** @internal */\nexport async function returnIteratorCatchingErrors(\n  iterator: AsyncIterator<unknown>,\n): Promise<void> {\n  try {\n    await iterator.return?.();\n  } catch {\n    // ignore errors\n  }\n}\n"]}

package/execution/returnIteratorCatchingErrors.mjs

@@ -2,8 +2,7 @@ export async function returnIteratorCatchingErrors(iterator) {
     try {
         await iterator.return?.();
     }
-    catch /* c8 ignore next 2 */ {
-        // ignore errors
+    catch {
     }
 }
 //# sourceMappingURL=returnIteratorCatchingErrors.js.map

package/execution/returnIteratorCatchingErrors.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"returnIteratorCatchingErrors.js","sourceRoot":"","sources":["../../src/execution/returnIteratorCatchingErrors.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAChD,QAAgC;IAEhC,IAAI,CAAC;QACH,MAAM,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC;IAC5B,CAAC;IAAC,MAAM,sBAAsB,CAAC,CAAC;QAC9B,gBAAgB;IAClB,CAAC;AACH,CAAC","sourcesContent":["export async function returnIteratorCatchingErrors(\n  iterator: AsyncIterator<unknown>,\n): Promise<void> {\n  try {\n    await iterator.return?.();\n  } catch /* c8 ignore next 2 */ {\n    // ignore errors\n  }\n}\n"]}
+{"version":3,"file":"returnIteratorCatchingErrors.js","sourceRoot":"","sources":["../../src/execution/returnIteratorCatchingErrors.ts"],"names":[],"mappings":"AACA,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAChD,QAAgC;IAEhC,IAAI,CAAC;QACH,MAAM,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;IAET,CAAC;AACH,CAAC","sourcesContent":["/** @internal */\nexport async function returnIteratorCatchingErrors(\n  iterator: AsyncIterator<unknown>,\n): Promise<void> {\n  try {\n    await iterator.return?.();\n  } catch {\n    // ignore errors\n  }\n}\n"]}

package/execution/values.d.mts

@@ -1,14 +1,25 @@
-import type { Maybe } from '../jsutils/Maybe.js';
-import type { ObjMap, ReadOnlyObjMap } from '../jsutils/ObjMap.js';
-import { GraphQLError } from '../error/GraphQLError.js';
-import type { DirectiveNode, FieldNode, FragmentSpreadNode, VariableDefinitionNode } from '../language/ast.js';
-import type { GraphQLField } from '../type/definition.js';
-import type { GraphQLDirective } from '../type/directives.js';
-import type { GraphQLSchema } from '../type/schema.js';
-import type { FragmentVariableValues } from './collectFields.js';
-import type { GraphQLVariableSignature } from './getVariableSignature.js';
+/** @category Values */
+import type { Maybe } from "../jsutils/Maybe.mjs";
+import type { ObjMap, ReadOnlyObjMap } from "../jsutils/ObjMap.mjs";
+import { GraphQLError } from "../error/GraphQLError.mjs";
+import type { DirectiveNode, FieldNode, FragmentSpreadNode, VariableDefinitionNode } from "../language/ast.mjs";
+import type { GraphQLField } from "../type/definition.mjs";
+import type { GraphQLDirective } from "../type/directives.mjs";
+import type { GraphQLSchema } from "../type/schema.mjs";
+import type { FragmentVariableValues } from "./collectFields.mjs";
+import type { GraphQLVariableSignature } from "./getVariableSignature.mjs";
+/**
+ * Coerced variable values prepared for execution.
+ *
+ * The `coerced` map contains runtime values keyed by variable name. The
+ * `sources` map records whether each value came from request input, an operation
+ * default, or a fragment-variable default so utilities can preserve defaults
+ * when replacing variables in literals.
+ */
 export interface VariableValues {
+    /** Source metadata for each variable value keyed by variable name. */
     readonly sources: ReadOnlyObjMap<VariableValueSource>;
+    /** Coerced runtime variable values keyed by variable name. */
     readonly coerced: ReadOnlyObjMap<unknown>;
 }
 interface VariableValueSource {
@@ -25,10 +36,85 @@ type VariableValuesOrErrors = {
 /**
  * Prepares an object map of variableValues of the correct type based on the
  * provided variable definitions and arbitrary input. If the input cannot be
- * parsed to match the variable definitions, a GraphQLError will be thrown.
+ * parsed to match the variable definitions, GraphQLError values are returned.
+ *
+ * Note: Returned maps use null prototypes to avoid collisions with
+ * Object prototype properties.
+ * @param schema - GraphQL schema to use.
+ * @param varDefNodes - The variable definition AST nodes to coerce.
+ * @param inputs - The runtime variable values keyed by variable name.
+ * @param options - Optional configuration for this operation.
+ * @param [options.maxErrors] - Maximum number of coercion errors to report.
+ * @param [options.hideSuggestions] - Whether suggestion text should be omitted
+ * from errors.
+ * @returns Coerced variable values with source metadata, or request errors.
+ * @example
+ * ```ts
+ * // Coerce provided variables and apply operation defaults.
+ * import assert from 'node:assert';
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { getVariableValues } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     reviews(stars: Int!, limit: Int = 10): [String]
+ *   }
+ * `);
+ * const document = parse(`
+ *   query ($stars: Int!, $limit: Int = 10) {
+ *     reviews(stars: $stars, limit: $limit)
+ *   }
+ * `);
+ * const operation = document.definitions[0];
+ *
+ * const result = getVariableValues(
+ *   schema,
+ *   operation.variableDefinitions,
+ *   { stars: '5' },
+ * );
+ *
+ * assert('variableValues' in result);
+ *
+ * result.variableValues.coerced; // => { stars: 5, limit: 10 }
+ * ```
+ * @example
+ * ```ts
+ * // This variant uses maxErrors to cap reported coercion errors.
+ * import assert from 'node:assert';
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { getVariableValues } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   input ReviewInput {
+ *     stars: Int!
+ *   }
+ *
+ *   type Query {
+ *     review(input: ReviewInput!): String
+ *   }
+ * `);
+ * const document = parse(`
+ *   query ($first: ReviewInput!, $second: ReviewInput!) {
+ *     first: review(input: $first)
+ *     second: review(input: $second)
+ *   }
+ * `);
+ * const operation = document.definitions[0];
+ *
+ * const result = getVariableValues(
+ *   schema,
+ *   operation.variableDefinitions,
+ *   { first: { stars: 'bad' }, second: { stars: 'also bad' } },
+ *   { maxErrors: 1 },
+ * );
  *
- * Note: The `coerced` and `sources` properties of VariableValues use null
- * prototype to avoid collisions with JavaScript's own property names.
+ * assert('errors' in result);
+ *
+ * result.errors.length; // => 2
+ * result.errors[1].message; // matches /error limit reached/
+ * ```
  */
 export declare function getVariableValues(schema: GraphQLSchema, varDefNodes: ReadonlyArray<VariableDefinitionNode>, inputs: {
     readonly [variable: string]: unknown;
@@ -36,13 +122,66 @@ export declare function getVariableValues(schema: GraphQLSchema, varDefNodes: Re
     maxErrors?: number;
     hideSuggestions?: boolean;
 }): VariableValuesOrErrors;
+/** @internal */
 export declare function getFragmentVariableValues(fragmentSpreadNode: FragmentSpreadNode, fragmentSignatures: ReadOnlyObjMap<GraphQLVariableSignature>, variableValues: VariableValues, fragmentVariableValues?: Maybe<FragmentVariableValues>, hideSuggestions?: Maybe<boolean>): FragmentVariableValues;
 /**
  * Prepares an object map of argument values given a list of argument
  * definitions and list of argument AST nodes.
  *
- * Note: The returned value uses a null prototype to avoid collisions with
+ * Note: Returned value uses a null prototype to avoid collisions with
  * JavaScript's own property names.
+ * @param def - Field or directive definition that declares the arguments.
+ * @param node - Field or directive AST node supplying argument literals.
+ * @param variableValues - Operation variable values returned by getVariableValues.
+ * @param fragmentVariableValues - Fragment variable values for the current fragment scope.
+ * @param hideSuggestions - Whether suggestion text should be omitted from errors.
+ * @returns A map of coerced argument values.
+ * @example
+ * ```ts
+ * // Read literal argument values and defaults.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { getArgumentValues } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     reviews(stars: Int!, limit: Int = 10): [String]
+ *   }
+ * `);
+ * const fieldDef = schema.getQueryType().getFields().reviews;
+ * const document = parse('{ reviews(stars: 5) }');
+ * const fieldNode = document.definitions[0].selectionSet.selections[0];
+ *
+ * getArgumentValues(fieldDef, fieldNode); // => { stars: 5, limit: 10 }
+ * ```
+ * @example
+ * ```ts
+ * // This variant resolves argument values from operation variables.
+ * import assert from 'node:assert';
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { getArgumentValues, getVariableValues } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     reviews(stars: Int!): [String]
+ *   }
+ * `);
+ * const fieldDef = schema.getQueryType().getFields().reviews;
+ * const document = parse('query ($stars: Int!) { reviews(stars: $stars) }');
+ * const operation = document.definitions[0];
+ * const fieldNode = document.definitions[0].selectionSet.selections[0];
+ * const variables = getVariableValues(
+ *   schema,
+ *   operation.variableDefinitions,
+ *   { stars: '5' },
+ * );
+ *
+ * assert('variableValues' in variables);
+ *
+ * getArgumentValues(fieldDef, fieldNode, variables.variableValues); // => { stars: 5 }
+ * getArgumentValues(fieldDef, fieldNode); // throws an error
+ * ```
  */
 export declare function getArgumentValues(def: GraphQLField<unknown, unknown> | GraphQLDirective, node: FieldNode | DirectiveNode, variableValues?: Maybe<VariableValues>, fragmentVariableValues?: Maybe<FragmentVariableValues>, hideSuggestions?: Maybe<boolean>): ObjMap<unknown>;
 /**
@@ -52,8 +191,51 @@ export declare function getArgumentValues(def: GraphQLField<unknown, unknown> |
  *
  * If the directive does not exist on the node, returns undefined.
  *
- * Note: The returned value uses a null prototype to avoid collisions with
+ * Note: Returned value uses a null prototype to avoid collisions with
  * JavaScript's own property names.
+ * @param directiveDef - Directive definition to read argument definitions from.
+ * @param node - AST node that may contain directives.
+ * @param node.directives - The directives on the AST node.
+ * @param variableValues - Operation variable values returned by getVariableValues.
+ * @param fragmentVariableValues - Fragment variable values for the current fragment scope.
+ * @param hideSuggestions - Whether suggestion text should be omitted from errors.
+ * @returns A map of coerced directive argument values, or undefined when absent.
+ * @example
+ * ```ts
+ * // Read literal directive arguments from a node.
+ * import { parse } from 'graphql/language';
+ * import { GraphQLSkipDirective } from 'graphql/type';
+ * import { getDirectiveValues } from 'graphql/execution';
+ *
+ * const document = parse('{ name @skip(if: true) }');
+ * const fieldNode = document.definitions[0].selectionSet.selections[0];
+ *
+ * getDirectiveValues(GraphQLSkipDirective, fieldNode); // => { if: true }
+ * ```
+ * @example
+ * ```ts
+ * // This variant resolves directive arguments from variables and handles absent directives.
+ * import assert from 'node:assert';
+ * import { parse } from 'graphql/language';
+ * import { GraphQLIncludeDirective } from 'graphql/type';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { getDirectiveValues, getVariableValues } from 'graphql/execution';
+ *
+ * const schema = buildSchema('type Query { name: String }');
+ * const document = parse('query ($includeName: Boolean!) { name @include(if: $includeName) }');
+ * const operation = document.definitions[0];
+ * const fieldNode = document.definitions[0].selectionSet.selections[0];
+ * const variables = getVariableValues(
+ *   schema,
+ *   operation.variableDefinitions,
+ *   { includeName: false },
+ * );
+ *
+ * assert('variableValues' in variables);
+ *
+ * getDirectiveValues(GraphQLIncludeDirective, fieldNode, variables.variableValues); // => { if: false }
+ * getDirectiveValues(GraphQLIncludeDirective, { directives: [] }); // => undefined
+ * ```
  */
 export declare function getDirectiveValues(directiveDef: GraphQLDirective, node: {
     readonly directives?: ReadonlyArray<DirectiveNode> | undefined;

package/execution/values.d.ts

@@ -1,14 +1,25 @@
-import type { Maybe } from '../jsutils/Maybe.js';
-import type { ObjMap, ReadOnlyObjMap } from '../jsutils/ObjMap.js';
-import { GraphQLError } from '../error/GraphQLError.js';
-import type { DirectiveNode, FieldNode, FragmentSpreadNode, VariableDefinitionNode } from '../language/ast.js';
-import type { GraphQLField } from '../type/definition.js';
-import type { GraphQLDirective } from '../type/directives.js';
-import type { GraphQLSchema } from '../type/schema.js';
-import type { FragmentVariableValues } from './collectFields.js';
-import type { GraphQLVariableSignature } from './getVariableSignature.js';
+/** @category Values */
+import type { Maybe } from "../jsutils/Maybe.js";
+import type { ObjMap, ReadOnlyObjMap } from "../jsutils/ObjMap.js";
+import { GraphQLError } from "../error/GraphQLError.js";
+import type { DirectiveNode, FieldNode, FragmentSpreadNode, VariableDefinitionNode } from "../language/ast.js";
+import type { GraphQLField } from "../type/definition.js";
+import type { GraphQLDirective } from "../type/directives.js";
+import type { GraphQLSchema } from "../type/schema.js";
+import type { FragmentVariableValues } from "./collectFields.js";
+import type { GraphQLVariableSignature } from "./getVariableSignature.js";
+/**
+ * Coerced variable values prepared for execution.
+ *
+ * The `coerced` map contains runtime values keyed by variable name. The
+ * `sources` map records whether each value came from request input, an operation
+ * default, or a fragment-variable default so utilities can preserve defaults
+ * when replacing variables in literals.
+ */
 export interface VariableValues {
+    /** Source metadata for each variable value keyed by variable name. */
     readonly sources: ReadOnlyObjMap<VariableValueSource>;
+    /** Coerced runtime variable values keyed by variable name. */
     readonly coerced: ReadOnlyObjMap<unknown>;
 }
 interface VariableValueSource {
@@ -25,10 +36,85 @@ type VariableValuesOrErrors = {
 /**
  * Prepares an object map of variableValues of the correct type based on the
  * provided variable definitions and arbitrary input. If the input cannot be
- * parsed to match the variable definitions, a GraphQLError will be thrown.
+ * parsed to match the variable definitions, GraphQLError values are returned.
+ *
+ * Note: Returned maps use null prototypes to avoid collisions with
+ * Object prototype properties.
+ * @param schema - GraphQL schema to use.
+ * @param varDefNodes - The variable definition AST nodes to coerce.
+ * @param inputs - The runtime variable values keyed by variable name.
+ * @param options - Optional configuration for this operation.
+ * @param [options.maxErrors] - Maximum number of coercion errors to report.
+ * @param [options.hideSuggestions] - Whether suggestion text should be omitted
+ * from errors.
+ * @returns Coerced variable values with source metadata, or request errors.
+ * @example
+ * ```ts
+ * // Coerce provided variables and apply operation defaults.
+ * import assert from 'node:assert';
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { getVariableValues } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     reviews(stars: Int!, limit: Int = 10): [String]
+ *   }
+ * `);
+ * const document = parse(`
+ *   query ($stars: Int!, $limit: Int = 10) {
+ *     reviews(stars: $stars, limit: $limit)
+ *   }
+ * `);
+ * const operation = document.definitions[0];
+ *
+ * const result = getVariableValues(
+ *   schema,
+ *   operation.variableDefinitions,
+ *   { stars: '5' },
+ * );
+ *
+ * assert('variableValues' in result);
+ *
+ * result.variableValues.coerced; // => { stars: 5, limit: 10 }
+ * ```
+ * @example
+ * ```ts
+ * // This variant uses maxErrors to cap reported coercion errors.
+ * import assert from 'node:assert';
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { getVariableValues } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   input ReviewInput {
+ *     stars: Int!
+ *   }
+ *
+ *   type Query {
+ *     review(input: ReviewInput!): String
+ *   }
+ * `);
+ * const document = parse(`
+ *   query ($first: ReviewInput!, $second: ReviewInput!) {
+ *     first: review(input: $first)
+ *     second: review(input: $second)
+ *   }
+ * `);
+ * const operation = document.definitions[0];
+ *
+ * const result = getVariableValues(
+ *   schema,
+ *   operation.variableDefinitions,
+ *   { first: { stars: 'bad' }, second: { stars: 'also bad' } },
+ *   { maxErrors: 1 },
+ * );
  *
- * Note: The `coerced` and `sources` properties of VariableValues use null
- * prototype to avoid collisions with JavaScript's own property names.
+ * assert('errors' in result);
+ *
+ * result.errors.length; // => 2
+ * result.errors[1].message; // matches /error limit reached/
+ * ```
  */
 export declare function getVariableValues(schema: GraphQLSchema, varDefNodes: ReadonlyArray<VariableDefinitionNode>, inputs: {
     readonly [variable: string]: unknown;
@@ -36,13 +122,66 @@ export declare function getVariableValues(schema: GraphQLSchema, varDefNodes: Re
     maxErrors?: number;
     hideSuggestions?: boolean;
 }): VariableValuesOrErrors;
+/** @internal */
 export declare function getFragmentVariableValues(fragmentSpreadNode: FragmentSpreadNode, fragmentSignatures: ReadOnlyObjMap<GraphQLVariableSignature>, variableValues: VariableValues, fragmentVariableValues?: Maybe<FragmentVariableValues>, hideSuggestions?: Maybe<boolean>): FragmentVariableValues;
 /**
  * Prepares an object map of argument values given a list of argument
  * definitions and list of argument AST nodes.
  *
- * Note: The returned value uses a null prototype to avoid collisions with
+ * Note: Returned value uses a null prototype to avoid collisions with
  * JavaScript's own property names.
+ * @param def - Field or directive definition that declares the arguments.
+ * @param node - Field or directive AST node supplying argument literals.
+ * @param variableValues - Operation variable values returned by getVariableValues.
+ * @param fragmentVariableValues - Fragment variable values for the current fragment scope.
+ * @param hideSuggestions - Whether suggestion text should be omitted from errors.
+ * @returns A map of coerced argument values.
+ * @example
+ * ```ts
+ * // Read literal argument values and defaults.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { getArgumentValues } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     reviews(stars: Int!, limit: Int = 10): [String]
+ *   }
+ * `);
+ * const fieldDef = schema.getQueryType().getFields().reviews;
+ * const document = parse('{ reviews(stars: 5) }');
+ * const fieldNode = document.definitions[0].selectionSet.selections[0];
+ *
+ * getArgumentValues(fieldDef, fieldNode); // => { stars: 5, limit: 10 }
+ * ```
+ * @example
+ * ```ts
+ * // This variant resolves argument values from operation variables.
+ * import assert from 'node:assert';
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { getArgumentValues, getVariableValues } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     reviews(stars: Int!): [String]
+ *   }
+ * `);
+ * const fieldDef = schema.getQueryType().getFields().reviews;
+ * const document = parse('query ($stars: Int!) { reviews(stars: $stars) }');
+ * const operation = document.definitions[0];
+ * const fieldNode = document.definitions[0].selectionSet.selections[0];
+ * const variables = getVariableValues(
+ *   schema,
+ *   operation.variableDefinitions,
+ *   { stars: '5' },
+ * );
+ *
+ * assert('variableValues' in variables);
+ *
+ * getArgumentValues(fieldDef, fieldNode, variables.variableValues); // => { stars: 5 }
+ * getArgumentValues(fieldDef, fieldNode); // throws an error
+ * ```
  */
 export declare function getArgumentValues(def: GraphQLField<unknown, unknown> | GraphQLDirective, node: FieldNode | DirectiveNode, variableValues?: Maybe<VariableValues>, fragmentVariableValues?: Maybe<FragmentVariableValues>, hideSuggestions?: Maybe<boolean>): ObjMap<unknown>;
 /**
@@ -52,8 +191,51 @@ export declare function getArgumentValues(def: GraphQLField<unknown, unknown> |
  *
  * If the directive does not exist on the node, returns undefined.
  *
- * Note: The returned value uses a null prototype to avoid collisions with
+ * Note: Returned value uses a null prototype to avoid collisions with
  * JavaScript's own property names.
+ * @param directiveDef - Directive definition to read argument definitions from.
+ * @param node - AST node that may contain directives.
+ * @param node.directives - The directives on the AST node.
+ * @param variableValues - Operation variable values returned by getVariableValues.
+ * @param fragmentVariableValues - Fragment variable values for the current fragment scope.
+ * @param hideSuggestions - Whether suggestion text should be omitted from errors.
+ * @returns A map of coerced directive argument values, or undefined when absent.
+ * @example
+ * ```ts
+ * // Read literal directive arguments from a node.
+ * import { parse } from 'graphql/language';
+ * import { GraphQLSkipDirective } from 'graphql/type';
+ * import { getDirectiveValues } from 'graphql/execution';
+ *
+ * const document = parse('{ name @skip(if: true) }');
+ * const fieldNode = document.definitions[0].selectionSet.selections[0];
+ *
+ * getDirectiveValues(GraphQLSkipDirective, fieldNode); // => { if: true }
+ * ```
+ * @example
+ * ```ts
+ * // This variant resolves directive arguments from variables and handles absent directives.
+ * import assert from 'node:assert';
+ * import { parse } from 'graphql/language';
+ * import { GraphQLIncludeDirective } from 'graphql/type';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { getDirectiveValues, getVariableValues } from 'graphql/execution';
+ *
+ * const schema = buildSchema('type Query { name: String }');
+ * const document = parse('query ($includeName: Boolean!) { name @include(if: $includeName) }');
+ * const operation = document.definitions[0];
+ * const fieldNode = document.definitions[0].selectionSet.selections[0];
+ * const variables = getVariableValues(
+ *   schema,
+ *   operation.variableDefinitions,
+ *   { includeName: false },
+ * );
+ *
+ * assert('variableValues' in variables);
+ *
+ * getDirectiveValues(GraphQLIncludeDirective, fieldNode, variables.variableValues); // => { if: false }
+ * getDirectiveValues(GraphQLIncludeDirective, { directives: [] }); // => undefined
+ * ```
  */
 export declare function getDirectiveValues(directiveDef: GraphQLDirective, node: {
     readonly directives?: ReadonlyArray<DirectiveNode> | undefined;