graphql 16.14.0 → 16.14.1

package/execution/values.js

@@ -27,14 +27,82 @@ var _typeFromAST = require('../utilities/typeFromAST.js');
 
 var _valueFromAST = require('../utilities/valueFromAST.js');
 
+/** @category Values */
+
 /**
  * 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: The returned value is a plain Object with a prototype, since it is
+ * Note: Returned value is a plain Object with a prototype, since it is
  * exposed to user code. Care should be taken to not pull values from the
  * Object prototype.
+ * @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 variable coercion options, including error limits.
+ * @returns Coerced variable values, or request errors.
+ * @example
+ * ```ts
+ * // Coerce provided variables and apply operation defaults.
+ * 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' },
+ * );
+ *
+ * result; // => { coerced: { stars: 5, limit: 10 } }
+ * ```
+ * @example
+ * ```ts
+ * // This variant uses maxErrors to cap reported coercion errors.
+ * 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 },
+ * );
+ *
+ * result.errors.length; // => 2
+ * result.errors[1].message; // matches /error limit reached/
+ * ```
  */
 function getVariableValues(schema, varDefNodes, inputs, options) {
   const errors = [];
@@ -159,9 +227,50 @@ function coerceVariableValues(schema, varDefNodes, inputs, onError) {
  * Prepares an object map of argument values given a list of argument
  * definitions and list of argument AST nodes.
  *
- * Note: The returned value is a plain Object with a prototype, since it is
+ * Note: Returned value is a plain Object with a prototype, since it is
  * exposed to user code. Care should be taken to not pull values from the
  * Object prototype.
+ * @param def - The field or directive definition whose arguments should be coerced.
+ * @param node - The AST node to inspect.
+ * @param variableValues - The runtime variable values keyed by variable name.
+ * @returns Coerced argument values keyed by argument name.
+ * @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 { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { getArgumentValues } 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 fieldNode = document.definitions[0].selectionSet.selections[0];
+ *
+ * getArgumentValues(fieldDef, fieldNode, { stars: 5 }); // => { stars: 5 }
+ * getArgumentValues(fieldDef, fieldNode, {}); // throws an error
+ * ```
  */
 
 function getArgumentValues(def, node, variableValues) {
@@ -268,6 +377,11 @@ function getArgumentValues(def, node, variableValues) {
 
   return { ...coercedValues };
 }
+/**
+ * AST node shape accepted by getDirectiveValues.
+ * @internal
+ */
+
 /**
  * Prepares an object map of argument values given a directive definition
  * and a AST node which may contain directives. Optionally also accepts a map
@@ -275,11 +389,41 @@ function getArgumentValues(def, node, variableValues) {
  *
  * If the directive does not exist on the node, returns undefined.
  *
- * Note: The returned value is a plain Object with a prototype, since it is
+ * Note: Returned value is a plain Object with a prototype, since it is
  * exposed to user code. Care should be taken to not pull values from the
  * Object prototype.
+ * @param directiveDef - The directive definition whose arguments should be coerced.
+ * @param node - The AST node to inspect.
+ * @param variableValues - The runtime variable values keyed by variable name.
+ * @returns Coerced directive argument values keyed by argument name.
+ * @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 { parse } from 'graphql/language';
+ * import { GraphQLIncludeDirective } from 'graphql/type';
+ * import { getDirectiveValues } from 'graphql/execution';
+ *
+ * const document = parse('query ($includeName: Boolean!) { name @include(if: $includeName) }');
+ * const fieldNode = document.definitions[0].selectionSet.selections[0];
+ *
+ * getDirectiveValues(GraphQLIncludeDirective, fieldNode, {
+ *   includeName: false,
+ * }); // => { if: false }
+ * getDirectiveValues(GraphQLIncludeDirective, { directives: [] }); // => undefined
+ * ```
  */
-
 function getDirectiveValues(directiveDef, node, variableValues) {
   var _node$directives;
 

package/execution/values.mjs

@@ -1,3 +1,4 @@
+/** @category Values */
 import { inspect } from '../jsutils/inspect.mjs';
 import { keyMap } from '../jsutils/keyMap.mjs';
 import { printPathArray } from '../jsutils/printPathArray.mjs';
@@ -12,11 +13,77 @@ import { valueFromAST } from '../utilities/valueFromAST.mjs';
 /**
  * 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: The returned value is a plain Object with a prototype, since it is
+ * Note: Returned value is a plain Object with a prototype, since it is
  * exposed to user code. Care should be taken to not pull values from the
  * Object prototype.
+ * @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 variable coercion options, including error limits.
+ * @returns Coerced variable values, or request errors.
+ * @example
+ * ```ts
+ * // Coerce provided variables and apply operation defaults.
+ * 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' },
+ * );
+ *
+ * result; // => { coerced: { stars: 5, limit: 10 } }
+ * ```
+ * @example
+ * ```ts
+ * // This variant uses maxErrors to cap reported coercion errors.
+ * 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 },
+ * );
+ *
+ * result.errors.length; // => 2
+ * result.errors[1].message; // matches /error limit reached/
+ * ```
  */
 export function getVariableValues(schema, varDefNodes, inputs, options) {
   const errors = [];
@@ -135,9 +202,50 @@ function coerceVariableValues(schema, varDefNodes, inputs, onError) {
  * Prepares an object map of argument values given a list of argument
  * definitions and list of argument AST nodes.
  *
- * Note: The returned value is a plain Object with a prototype, since it is
+ * Note: Returned value is a plain Object with a prototype, since it is
  * exposed to user code. Care should be taken to not pull values from the
  * Object prototype.
+ * @param def - The field or directive definition whose arguments should be coerced.
+ * @param node - The AST node to inspect.
+ * @param variableValues - The runtime variable values keyed by variable name.
+ * @returns Coerced argument values keyed by argument name.
+ * @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 { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { getArgumentValues } 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 fieldNode = document.definitions[0].selectionSet.selections[0];
+ *
+ * getArgumentValues(fieldDef, fieldNode, { stars: 5 }); // => { stars: 5 }
+ * getArgumentValues(fieldDef, fieldNode, {}); // throws an error
+ * ```
  */
 
 export function getArgumentValues(def, node, variableValues) {
@@ -231,6 +339,11 @@ export function getArgumentValues(def, node, variableValues) {
 
   return { ...coercedValues };
 }
+/**
+ * AST node shape accepted by getDirectiveValues.
+ * @internal
+ */
+
 /**
  * Prepares an object map of argument values given a directive definition
  * and a AST node which may contain directives. Optionally also accepts a map
@@ -238,11 +351,41 @@ export function getArgumentValues(def, node, variableValues) {
  *
  * If the directive does not exist on the node, returns undefined.
  *
- * Note: The returned value is a plain Object with a prototype, since it is
+ * Note: Returned value is a plain Object with a prototype, since it is
  * exposed to user code. Care should be taken to not pull values from the
  * Object prototype.
+ * @param directiveDef - The directive definition whose arguments should be coerced.
+ * @param node - The AST node to inspect.
+ * @param variableValues - The runtime variable values keyed by variable name.
+ * @returns Coerced directive argument values keyed by argument name.
+ * @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 { parse } from 'graphql/language';
+ * import { GraphQLIncludeDirective } from 'graphql/type';
+ * import { getDirectiveValues } from 'graphql/execution';
+ *
+ * const document = parse('query ($includeName: Boolean!) { name @include(if: $includeName) }');
+ * const fieldNode = document.definitions[0].selectionSet.selections[0];
+ *
+ * getDirectiveValues(GraphQLIncludeDirective, fieldNode, {
+ *   includeName: false,
+ * }); // => { if: false }
+ * getDirectiveValues(GraphQLIncludeDirective, { directives: [] }); // => undefined
+ * ```
  */
-
 export function getDirectiveValues(directiveDef, node, variableValues) {
   var _node$directives;
 

package/graphql.d.ts

@@ -7,61 +7,183 @@ import type {
 import type { GraphQLSchema } from './type/schema';
 import type { ExecutionResult } from './execution/execute';
 /**
- * This is the primary entry point function for fulfilling GraphQL operations
- * by parsing, validating, and executing a GraphQL document along side a
- * GraphQL schema.
- *
- * More sophisticated GraphQL servers, such as those which persist queries,
- * may wish to separate the validation and execution phases to a static time
- * tooling step, and a server runtime step.
- *
- * Accepts either an object with named arguments, or individual arguments:
- *
- * schema:
- *    The GraphQL type system to use when validating and executing a query.
- * source:
- *    A GraphQL language formatted string representing the requested operation.
- * rootValue:
- *    The value provided as the first argument to resolver functions on the top
- *    level type (e.g. the query object type).
- * contextValue:
- *    The context value is provided as an argument to resolver functions after
- *    field arguments. It is used to pass shared information useful at any point
- *    during executing this query, for example the currently logged in user and
- *    connections to databases or other services.
- * variableValues:
- *    A mapping of variable name to runtime value to use for all variables
- *    defined in the requestString.
- * operationName:
- *    The name of the operation to use if requestString contains multiple
- *    possible operations. Can be omitted if requestString contains only
- *    one operation.
- * fieldResolver:
- *    A resolver function to use when one is not provided by the schema.
- *    If not provided, the default field resolver is used (which looks for a
- *    value or method on the source value with the field's name).
- * typeResolver:
- *    A type resolver function to use when none is provided by the schema.
- *    If not provided, the default type resolver is used (which looks for a
- *    `__typename` field or alternatively calls the `isTypeOf` method).
+ * Describes the input object accepted by `graphql` and `graphqlSync`.
+ *
+ * These arguments describe the full parse, validate, and execute lifecycle for
+ * a GraphQL request.
+ * @category Request Pipeline
  */
 export interface GraphQLArgs {
+  /** The GraphQL type system to use when validating and executing a query. */
   schema: GraphQLSchema;
+  /**
+   * A GraphQL language-formatted string or source object representing the
+   * requested operation.
+   */
   source: string | Source;
+  /**
+   * The value provided as the first argument to resolver functions on the top
+   * level type, such as the query object type.
+   */
   rootValue?: unknown;
+  /**
+   * Application context value passed to every resolver.
+   *
+   * Use this for shared request data such as the currently logged in user and
+   * connections to databases or other services.
+   */
   contextValue?: unknown;
+  /** A mapping of variable name to runtime value for variables defined by the operation. */
   variableValues?: Maybe<{
     readonly [variable: string]: unknown;
   }>;
+  /**
+   * The operation to execute when the source contains multiple possible
+   * operations. This can be omitted when the source contains only one operation.
+   */
   operationName?: Maybe<string>;
+  /**
+   * A resolver function to use when one is not provided by the schema.
+   *
+   * If not provided, the default field resolver is used, which looks for a value
+   * or method on the source value with the field's name.
+   */
   fieldResolver?: Maybe<GraphQLFieldResolver<any, any>>;
+  /**
+   * A type resolver function to use when none is provided by the schema.
+   *
+   * If not provided, the default type resolver is used, which looks for a
+   * `__typename` field or alternatively calls the `isTypeOf` method.
+   */
   typeResolver?: Maybe<GraphQLTypeResolver<any, any>>;
 }
+/**
+ * Parses, validates, and executes a GraphQL document against a schema.
+ *
+ * This is the primary entry point for fulfilling GraphQL operations. Use this
+ * when you want a single-call request lifecycle that returns a promise in all
+ * cases.
+ *
+ * More sophisticated GraphQL servers, such as those which persist queries, may
+ * wish to separate the validation and execution phases to a static-time tooling
+ * step and a server runtime step.
+ * @param args - Request execution arguments, including schema and source.
+ * @returns A promise that resolves to an execution result or validation errors.
+ * @example
+ * ```ts
+ * // Execute a complete asynchronous request with variables.
+ * import { graphql, buildSchema } from 'graphql';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting(name: String!): String
+ *   }
+ * `);
+ *
+ * const result = await graphql({
+ *   schema,
+ *   source: 'query SayHello($name: String!) { greeting(name: $name) }',
+ *   rootValue: {
+ *     greeting: ({ name }) => `Hello, ${name}!`,
+ *   },
+ *   variableValues: { name: 'Ada' },
+ *   operationName: 'SayHello',
+ * });
+ *
+ * result; // => { data: { greeting: 'Hello, Ada!' } }
+ * ```
+ * @example
+ * ```ts
+ * // This variant supplies context plus custom field and type resolvers.
+ * import { graphql, buildSchema } from 'graphql';
+ *
+ * const schema = buildSchema(`
+ *   interface Named {
+ *     name: String!
+ *   }
+ *
+ *   type User implements Named {
+ *     name: String!
+ *   }
+ *
+ *   type Query {
+ *     viewer: Named
+ *   }
+ * `);
+ *
+ * const result = await graphql({
+ *   schema,
+ *   source: '{ viewer { __typename name } }',
+ *   rootValue: { viewer: { kind: 'user', name: 'Ada' } },
+ *   contextValue: { locale: 'en' },
+ *   fieldResolver: (source, _args, context, info) => {
+ *     context.locale; // => 'en'
+ *     return source[info.fieldName];
+ *   },
+ *   typeResolver: (value) => {
+ *     return value.kind === 'user' ? 'User' : undefined;
+ *   },
+ * });
+ *
+ * result; // => { data: { viewer: { __typename: 'User', name: 'Ada' } } }
+ * ```
+ * @category Request Pipeline
+ */
 export declare function graphql(args: GraphQLArgs): Promise<ExecutionResult>;
 /**
- * The graphqlSync function also fulfills GraphQL operations by parsing,
- * validating, and executing a GraphQL document along side a GraphQL schema.
- * However, it guarantees to complete synchronously (or throw an error) assuming
- * that all field resolvers are also synchronous.
+ * Parses, validates, and executes a GraphQL document synchronously.
+ *
+ * This function guarantees that execution completes synchronously, or throws an
+ * error, assuming that all field resolvers are also synchronous. It throws when
+ * any resolver returns a promise.
+ * @param args - Request execution arguments, including schema and source.
+ * @returns Completed execution output, or request errors if parsing or
+ * validation fails.
+ * @example
+ * ```ts
+ * // Execute a complete synchronous request with variables.
+ * import { graphqlSync, buildSchema } from 'graphql';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting(name: String!): String
+ *   }
+ * `);
+ *
+ * const result = graphqlSync({
+ *   schema,
+ *   source: 'query SayHello($name: String!) { greeting(name: $name) }',
+ *   rootValue: {
+ *     greeting: ({ name }) => `Hello, ${name}!`,
+ *   },
+ *   variableValues: { name: 'Ada' },
+ *   operationName: 'SayHello',
+ * });
+ *
+ * result; // => { data: { greeting: 'Hello, Ada!' } }
+ * ```
+ * @example
+ * ```ts
+ * // This variant uses a synchronous custom field resolver and context.
+ * import { graphqlSync, buildSchema } from 'graphql';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ *
+ * const result = graphqlSync({
+ *   schema,
+ *   source: '{ greeting }',
+ *   fieldResolver: (_source, _args, contextValue) => {
+ *     return contextValue.defaultGreeting;
+ *   },
+ *   contextValue: { defaultGreeting: 'Hello' },
+ * });
+ *
+ * result; // => { data: { greeting: 'Hello' } }
+ * ```
+ * @category Request Pipeline
  */
 export declare function graphqlSync(args: GraphQLArgs): ExecutionResult;