graphql 16.14.0 → 16.14.1

package/execution/subscribe.js

@@ -26,10 +26,12 @@ var _mapAsyncIterator = require('./mapAsyncIterator.js');
 
 var _values = require('./values.js');
 
+/** @category Subscriptions */
+
 /**
  * Implements the "Subscribe" algorithm described in the GraphQL specification.
  *
- * Returns a Promise which resolves to either an AsyncIterator (if successful)
+ * Returns a Promise that resolves to either an AsyncIterator (if successful)
  * or an ExecutionResult (error). The promise will be rejected if the schema or
  * other arguments to this function are invalid, or if the resolved event stream
  * is not an async iterable.
@@ -45,7 +47,122 @@ var _values = require('./values.js');
  * If the operation succeeded, the promise resolves to an AsyncIterator, which
  * yields a stream of ExecutionResults representing the response stream.
  *
- * Accepts either an object with named arguments, or individual arguments.
+ * Each payload yielded by the source event stream is executed with the payload
+ * as the root value. This maps the subscription source stream into the response
+ * stream described by the GraphQL specification.
+ *
+ * Accepts an object with named arguments.
+ * @param args - The arguments used to perform the operation.
+ * @returns A source stream mapped to execution results, or an execution result
+ * containing subscription errors.
+ * @example
+ * ```ts
+ * // Use a same-named rootValue function to provide the source event stream.
+ * import assert from 'node:assert';
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { subscribe } from 'graphql/execution';
+ *
+ * async function* greetings() {
+ *   yield { greeting: 'Hello' };
+ *   yield { greeting: 'Bonjour' };
+ * }
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     noop: String
+ *   }
+ *
+ *   type Subscription {
+ *     greeting: String
+ *   }
+ * `);
+ *
+ * const result = await subscribe({
+ *   schema,
+ *   document: parse('subscription { greeting }'),
+ *   rootValue: { greeting: () => greetings() },
+ * });
+ *
+ * assert('next' in result);
+ *
+ * const firstPayload = await result.next();
+ * firstPayload.value; // => { data: { greeting: 'Hello' } }
+ * ```
+ * @example
+ * ```ts
+ * // This variant supplies events through a custom subscribeFieldResolver.
+ * import assert from 'node:assert';
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { subscribe } from 'graphql/execution';
+ *
+ * async function* defaultGreetings() {
+ *   yield { greeting: 'Hello' };
+ * }
+ *
+ * async function* frenchGreetings() {
+ *   yield { greeting: 'Bonjour' };
+ * }
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     noop: String
+ *   }
+ *
+ *   type Subscription {
+ *     greeting(locale: String): String
+ *   }
+ * `);
+ *
+ * const result = await subscribe({
+ *   schema,
+ *   document: parse(
+ *     'subscription Greeting($locale: String) { greeting(locale: $locale) }',
+ *   ),
+ *   rootValue: {
+ *     greeting: (args, contextValue) => {
+ *       const locale = args.locale ?? contextValue.defaultLocale;
+ *       return locale === 'fr' ? frenchGreetings() : defaultGreetings();
+ *     },
+ *   },
+ *   contextValue: { defaultLocale: 'fr' },
+ *   variableValues: { locale: 'fr' },
+ *   operationName: 'Greeting',
+ *   subscribeFieldResolver: (rootValue, args, contextValue, info) => {
+ *     args.locale; // => 'fr'
+ *     return rootValue[info.fieldName](args, contextValue);
+ *   },
+ * });
+ *
+ * assert('next' in result);
+ *
+ * const firstPayload = await result.next();
+ * firstPayload.value; // => { data: { greeting: 'Bonjour' } }
+ * ```
+ * @example
+ * ```ts
+ * // This variant shows the error result when the schema has no subscription root.
+ * import assert from 'node:assert';
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { subscribe } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     noop: String
+ *   }
+ * `);
+ *
+ * const result = await subscribe({
+ *   schema,
+ *   document: parse('subscription { greeting }'),
+ * });
+ *
+ * assert('errors' in result);
+ *
+ * result.errors[0].message; // => 'Schema is not configured to execute subscription operation.'
+ * ```
  */
 async function subscribe(args) {
   // Temporary for v15 to v16 migration. Remove in v17
@@ -58,15 +175,10 @@ async function subscribe(args) {
 
   if (!(0, _isAsyncIterable.isAsyncIterable)(resultOrStream)) {
     return resultOrStream;
-  } // For each payload yielded from a subscription, map it over the normal
-  // GraphQL `execute` function, with `payload` as the rootValue.
-  // This implements the "MapSourceToResponseEvent" algorithm described in
-  // the GraphQL specification. The `execute` function provides the
-  // "ExecuteSubscriptionEvent" algorithm, as it is nearly identical to the
-  // "ExecuteQuery" algorithm, for which `execute` is also used.
+  }
 
   const mapSourceToResponse = (payload) =>
-    (0, _execute.execute)({ ...args, rootValue: payload }); // Map every source value to a ExecutionResult value as described above.
+    (0, _execute.execute)({ ...args, rootValue: payload });
 
   return (0, _mapAsyncIterator.mapAsyncIterator)(
     resultOrStream,
@@ -96,7 +208,7 @@ function toNormalizedArgs(args) {
  * Implements the "CreateSourceEventStream" algorithm described in the
  * GraphQL specification, resolving the subscription source event stream.
  *
- * Returns a Promise which resolves to either an AsyncIterable (if successful)
+ * Returns a Promise that resolves to either an AsyncIterable (if successful)
  * or an ExecutionResult (error). The promise will be rejected if the schema or
  * other arguments to this function are invalid, or if the resolved event stream
  * is not an async iterable.
@@ -105,7 +217,7 @@ function toNormalizedArgs(args) {
  * compliant subscription, a GraphQL Response (ExecutionResult) with
  * descriptive errors and no data will be returned.
  *
- * If the the source stream could not be created due to faulty subscription
+ * If the source stream could not be created due to faulty subscription
  * resolver logic or underlying systems, the promise will resolve to a single
  * ExecutionResult containing `errors` and no `data`.
  *
@@ -119,8 +231,39 @@ function toNormalizedArgs(args) {
  * different process or machine than the stateless GraphQL execution engine,
  * or otherwise separating these two steps. For more on this, see the
  * "Supporting Subscriptions at Scale" information in the GraphQL specification.
+ * @param args - The arguments used to perform the operation.
+ * @returns The source event stream, or an execution result containing subscription errors.
+ * @example
+ * ```ts
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { createSourceEventStream } from 'graphql/execution';
+ *
+ * async function* greetings() {
+ *   yield { greeting: 'Hello' };
+ * }
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     noop: String
+ *   }
+ *
+ *   type Subscription {
+ *     greeting: String
+ *   }
+ * `);
+ *
+ * const stream = await createSourceEventStream({
+ *   schema,
+ *   document: parse('subscription { greeting }'),
+ *   rootValue: { greeting: () => greetings() },
+ * });
+ *
+ * Symbol.asyncIterator in stream; // => true
+ * ```
  */
 
+/** @internal */
 async function createSourceEventStream(...rawArgs) {
   const args = toNormalizedArgs(rawArgs);
   const { schema, document, variableValues } = args; // If arguments are missing or incorrectly typed, this is an internal

package/execution/subscribe.mjs

@@ -1,3 +1,4 @@
+/** @category Subscriptions */
 import { devAssert } from '../jsutils/devAssert.mjs';
 import { inspect } from '../jsutils/inspect.mjs';
 import { isAsyncIterable } from '../jsutils/isAsyncIterable.mjs';
@@ -18,7 +19,7 @@ import { getArgumentValues } from './values.mjs';
 /**
  * Implements the "Subscribe" algorithm described in the GraphQL specification.
  *
- * Returns a Promise which resolves to either an AsyncIterator (if successful)
+ * Returns a Promise that resolves to either an AsyncIterator (if successful)
  * or an ExecutionResult (error). The promise will be rejected if the schema or
  * other arguments to this function are invalid, or if the resolved event stream
  * is not an async iterable.
@@ -34,7 +35,122 @@ import { getArgumentValues } from './values.mjs';
  * If the operation succeeded, the promise resolves to an AsyncIterator, which
  * yields a stream of ExecutionResults representing the response stream.
  *
- * Accepts either an object with named arguments, or individual arguments.
+ * Each payload yielded by the source event stream is executed with the payload
+ * as the root value. This maps the subscription source stream into the response
+ * stream described by the GraphQL specification.
+ *
+ * Accepts an object with named arguments.
+ * @param args - The arguments used to perform the operation.
+ * @returns A source stream mapped to execution results, or an execution result
+ * containing subscription errors.
+ * @example
+ * ```ts
+ * // Use a same-named rootValue function to provide the source event stream.
+ * import assert from 'node:assert';
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { subscribe } from 'graphql/execution';
+ *
+ * async function* greetings() {
+ *   yield { greeting: 'Hello' };
+ *   yield { greeting: 'Bonjour' };
+ * }
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     noop: String
+ *   }
+ *
+ *   type Subscription {
+ *     greeting: String
+ *   }
+ * `);
+ *
+ * const result = await subscribe({
+ *   schema,
+ *   document: parse('subscription { greeting }'),
+ *   rootValue: { greeting: () => greetings() },
+ * });
+ *
+ * assert('next' in result);
+ *
+ * const firstPayload = await result.next();
+ * firstPayload.value; // => { data: { greeting: 'Hello' } }
+ * ```
+ * @example
+ * ```ts
+ * // This variant supplies events through a custom subscribeFieldResolver.
+ * import assert from 'node:assert';
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { subscribe } from 'graphql/execution';
+ *
+ * async function* defaultGreetings() {
+ *   yield { greeting: 'Hello' };
+ * }
+ *
+ * async function* frenchGreetings() {
+ *   yield { greeting: 'Bonjour' };
+ * }
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     noop: String
+ *   }
+ *
+ *   type Subscription {
+ *     greeting(locale: String): String
+ *   }
+ * `);
+ *
+ * const result = await subscribe({
+ *   schema,
+ *   document: parse(
+ *     'subscription Greeting($locale: String) { greeting(locale: $locale) }',
+ *   ),
+ *   rootValue: {
+ *     greeting: (args, contextValue) => {
+ *       const locale = args.locale ?? contextValue.defaultLocale;
+ *       return locale === 'fr' ? frenchGreetings() : defaultGreetings();
+ *     },
+ *   },
+ *   contextValue: { defaultLocale: 'fr' },
+ *   variableValues: { locale: 'fr' },
+ *   operationName: 'Greeting',
+ *   subscribeFieldResolver: (rootValue, args, contextValue, info) => {
+ *     args.locale; // => 'fr'
+ *     return rootValue[info.fieldName](args, contextValue);
+ *   },
+ * });
+ *
+ * assert('next' in result);
+ *
+ * const firstPayload = await result.next();
+ * firstPayload.value; // => { data: { greeting: 'Bonjour' } }
+ * ```
+ * @example
+ * ```ts
+ * // This variant shows the error result when the schema has no subscription root.
+ * import assert from 'node:assert';
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { subscribe } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     noop: String
+ *   }
+ * `);
+ *
+ * const result = await subscribe({
+ *   schema,
+ *   document: parse('subscription { greeting }'),
+ * });
+ *
+ * assert('errors' in result);
+ *
+ * result.errors[0].message; // => 'Schema is not configured to execute subscription operation.'
+ * ```
  */
 
 export async function subscribe(args) {
@@ -48,15 +164,10 @@ export async function subscribe(args) {
 
   if (!isAsyncIterable(resultOrStream)) {
     return resultOrStream;
-  } // For each payload yielded from a subscription, map it over the normal
-  // GraphQL `execute` function, with `payload` as the rootValue.
-  // This implements the "MapSourceToResponseEvent" algorithm described in
-  // the GraphQL specification. The `execute` function provides the
-  // "ExecuteSubscriptionEvent" algorithm, as it is nearly identical to the
-  // "ExecuteQuery" algorithm, for which `execute` is also used.
+  }
 
   const mapSourceToResponse = (payload) =>
-    execute({ ...args, rootValue: payload }); // Map every source value to a ExecutionResult value as described above.
+    execute({ ...args, rootValue: payload });
 
   return mapAsyncIterator(resultOrStream, mapSourceToResponse);
 }
@@ -83,7 +194,7 @@ function toNormalizedArgs(args) {
  * Implements the "CreateSourceEventStream" algorithm described in the
  * GraphQL specification, resolving the subscription source event stream.
  *
- * Returns a Promise which resolves to either an AsyncIterable (if successful)
+ * Returns a Promise that resolves to either an AsyncIterable (if successful)
  * or an ExecutionResult (error). The promise will be rejected if the schema or
  * other arguments to this function are invalid, or if the resolved event stream
  * is not an async iterable.
@@ -92,7 +203,7 @@ function toNormalizedArgs(args) {
  * compliant subscription, a GraphQL Response (ExecutionResult) with
  * descriptive errors and no data will be returned.
  *
- * If the the source stream could not be created due to faulty subscription
+ * If the source stream could not be created due to faulty subscription
  * resolver logic or underlying systems, the promise will resolve to a single
  * ExecutionResult containing `errors` and no `data`.
  *
@@ -106,8 +217,39 @@ function toNormalizedArgs(args) {
  * different process or machine than the stateless GraphQL execution engine,
  * or otherwise separating these two steps. For more on this, see the
  * "Supporting Subscriptions at Scale" information in the GraphQL specification.
+ * @param args - The arguments used to perform the operation.
+ * @returns The source event stream, or an execution result containing subscription errors.
+ * @example
+ * ```ts
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { createSourceEventStream } from 'graphql/execution';
+ *
+ * async function* greetings() {
+ *   yield { greeting: 'Hello' };
+ * }
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     noop: String
+ *   }
+ *
+ *   type Subscription {
+ *     greeting: String
+ *   }
+ * `);
+ *
+ * const stream = await createSourceEventStream({
+ *   schema,
+ *   document: parse('subscription { greeting }'),
+ *   rootValue: { greeting: () => greetings() },
+ * });
+ *
+ * Symbol.asyncIterator in stream; // => true
+ * ```
  */
 
+/** @internal */
 export async function createSourceEventStream(...rawArgs) {
   const args = toNormalizedArgs(rawArgs);
   const { schema, document, variableValues } = args; // If arguments are missing or incorrectly typed, this is an internal

package/execution/values.d.ts

@@ -1,3 +1,4 @@
+/** @category Values */
 import type { Maybe } from '../jsutils/Maybe';
 import type { ObjMap } from '../jsutils/ObjMap';
 import { GraphQLError } from '../error/GraphQLError';
@@ -20,14 +21,91 @@ declare type CoercedVariableValues =
       };
       errors?: never;
     };
+/**
+ * Options used when coercing variable values before execution.
+ * @internal
+ */
+export interface GetVariableValuesOptions {
+  /**
+   * Maximum number of variable coercion errors before coercion stops.
+   * @internal
+   */
+  maxErrors?: number;
+}
 /**
  * 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 declare function getVariableValues(
   schema: GraphQLSchema,
@@ -35,17 +113,56 @@ export declare function getVariableValues(
   inputs: {
     readonly [variable: string]: unknown;
   },
-  options?: {
-    maxErrors?: number;
-  },
+  options?: GetVariableValuesOptions,
 ): CoercedVariableValues;
 /**
  * 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 declare function getArgumentValues(
   def: GraphQLField<unknown, unknown> | GraphQLDirective,
@@ -54,6 +171,17 @@ export declare function getArgumentValues(
 ): {
   [argument: string]: unknown;
 };
+/**
+ * AST node shape accepted by getDirectiveValues.
+ * @internal
+ */
+export interface DirectiveValuesNode {
+  /**
+   * Directives attached to the AST node.
+   * @internal
+   */
+  readonly directives?: ReadonlyArray<DirectiveNode>;
+}
 /**
  * Prepares an object map of argument values given a directive definition
  * and a AST node which may contain directives. Optionally also accepts a map
@@ -61,15 +189,44 @@ export declare function getArgumentValues(
  *
  * 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 declare function getDirectiveValues(
   directiveDef: GraphQLDirective,
-  node: {
-    readonly directives?: ReadonlyArray<DirectiveNode>;
-  },
+  node: DirectiveValuesNode,
   variableValues?: Maybe<ObjMap<unknown>>,
 ):
   | undefined