graphql 16.14.0 → 16.14.1

package/graphql.js

@@ -18,15 +18,137 @@ var _validate2 = require('./validation/validate.js');
 
 var _execute = require('./execution/execute.js');
 
+/**
+ * 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
+ */
 function graphql(args) {
   // Always return a Promise for a consistent API.
   return new Promise((resolve) => resolve(graphqlImpl(args)));
 }
 /**
- * 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
  */
 
 function graphqlSync(args) {

package/graphql.mjs

@@ -5,54 +5,144 @@ import { validateSchema } from './type/validate.mjs';
 import { validate } from './validation/validate.mjs';
 import { execute } from './execution/execute.mjs';
 /**
- * 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
  */
 
+/**
+ * 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 function graphql(args) {
   // Always return a Promise for a consistent API.
   return new Promise((resolve) => resolve(graphqlImpl(args)));
 }
 /**
- * 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 function graphqlSync(args) {

package/index.d.ts

@@ -1,28 +1,22 @@
 /**
- * GraphQL.js provides a reference implementation for the GraphQL specification
- * but is also a useful utility for operating on GraphQL files and building
- * sophisticated tools.
+ * The root `graphql` package re-exports the public GraphQL.js API from its
+ * submodules and provides the high-level request pipeline helpers defined in
+ * this module.
  *
- * This primary module exports a general purpose function for fulfilling all
- * steps of the GraphQL specification in a single operation, but also includes
- * utilities for every part of the GraphQL specification:
- *
- *   - Parsing the GraphQL language.
- *   - Building a GraphQL type schema.
- *   - Validating a GraphQL request against a type schema.
- *   - Executing a GraphQL request against a type schema.
- *
- * This also includes utility functions for operating on GraphQL types and
- * GraphQL documents to facilitate building tools.
- *
- * You may also import from each sub-directory directly. For example, the
- * following two import statements are equivalent:
+ * You can import public exports from GraphQL.js modules through the root
+ * `graphql` package or through their module-specific entry point. For example,
+ * these two references resolve to the same `parse` function:
  *
  * ```ts
  * import { parse } from 'graphql';
  * import { parse } from 'graphql/language';
  * ```
  *
+ * Use the root package when you want a single import surface, or use submodules
+ * such as `graphql/language`, `graphql/type`, `graphql/execution`, and
+ * `graphql/utilities` when you want module-focused imports. This module also
+ * defines root-only APIs, such as request pipeline helpers and version
+ * metadata, that do not belong to a narrower submodule.
  * @packageDocumentation
  */
 export { version, versionInfo } from './version';

package/index.mjs

@@ -1,32 +1,26 @@
 /**
- * GraphQL.js provides a reference implementation for the GraphQL specification
- * but is also a useful utility for operating on GraphQL files and building
- * sophisticated tools.
+ * The root `graphql` package re-exports the public GraphQL.js API from its
+ * submodules and provides the high-level request pipeline helpers defined in
+ * this module.
  *
- * This primary module exports a general purpose function for fulfilling all
- * steps of the GraphQL specification in a single operation, but also includes
- * utilities for every part of the GraphQL specification:
- *
- *   - Parsing the GraphQL language.
- *   - Building a GraphQL type schema.
- *   - Validating a GraphQL request against a type schema.
- *   - Executing a GraphQL request against a type schema.
- *
- * This also includes utility functions for operating on GraphQL types and
- * GraphQL documents to facilitate building tools.
- *
- * You may also import from each sub-directory directly. For example, the
- * following two import statements are equivalent:
+ * You can import public exports from GraphQL.js modules through the root
+ * `graphql` package or through their module-specific entry point. For example,
+ * these two references resolve to the same `parse` function:
  *
  * ```ts
  * import { parse } from 'graphql';
  * import { parse } from 'graphql/language';
  * ```
  *
+ * Use the root package when you want a single import surface, or use submodules
+ * such as `graphql/language`, `graphql/type`, `graphql/execution`, and
+ * `graphql/utilities` when you want module-focused imports. This module also
+ * defines root-only APIs, such as request pipeline helpers and version
+ * metadata, that do not belong to a narrower submodule.
  * @packageDocumentation
  */
-// The GraphQL.js version info.
-export { version, versionInfo } from './version.mjs'; // The primary entry point into fulfilling a GraphQL request.
+// Version constants for the GraphQL.js package.
+export { version, versionInfo } from './version.mjs'; // Top-level helpers for fulfilling a GraphQL request.
 
 export { graphql, graphqlSync } from './graphql.mjs'; // Create and operate on GraphQL type definitions and schema.
 

package/jsutils/Maybe.d.ts

@@ -1,2 +1,6 @@
-/** Conveniently represents flow's "Maybe" type https://flow.org/en/docs/types/maybe/ */
+/**
+ * Conveniently represents flow's "Maybe" type https://flow.org/en/docs/types/maybe/
+ *
+ * @internal
+ */
 export declare type Maybe<T> = null | undefined | T;

package/jsutils/ObjMap.d.ts

@@ -1,14 +1,18 @@
+/** @internal */
 export interface ObjMap<T> {
   [key: string]: T;
 }
+/** @internal */
 export declare type ObjMapLike<T> =
   | ObjMap<T>
   | {
       [key: string]: T;
     };
+/** @internal */
 export interface ReadOnlyObjMap<T> {
   readonly [key: string]: T;
 }
+/** @internal */
 export declare type ReadOnlyObjMapLike<T> =
   | ReadOnlyObjMap<T>
   | {

package/jsutils/Path.d.ts

@@ -1,11 +1,18 @@
+/** @category Paths */
 import type { Maybe } from './Maybe';
+/** Represents a linked response path from a field back to the root response. */
 export interface Path {
+  /** The previous segment in the linked response path, or undefined at the root. */
   readonly prev: Path | undefined;
+  /** The field name or list index for this response path segment. */
   readonly key: string | number;
+  /** The runtime object type name associated with this path segment, if known. */
   readonly typename: string | undefined;
 }
 /**
  * Given a Path and a key, return a new Path containing the new key.
+ *
+ * @internal
  */
 export declare function addPath(
   prev: Readonly<Path> | undefined,
@@ -14,6 +21,29 @@ export declare function addPath(
 ): Path;
 /**
  * Given a Path, return an Array of the path keys.
+ * @param path - The linked response path to flatten.
+ * @returns An array of response path keys from root to leaf.
+ * @example
+ * ```ts
+ * import { pathToArray } from 'graphql/jsutils/Path';
+ *
+ * const path = {
+ *   prev: {
+ *     prev: {
+ *       prev: undefined,
+ *       key: 'viewer',
+ *       typename: 'Query',
+ *     },
+ *     key: 'friends',
+ *     typename: 'User',
+ *   },
+ *   key: 0,
+ *   typename: undefined,
+ * };
+ *
+ * pathToArray(path); // => ['viewer', 'friends', 0]
+ * pathToArray(undefined); // => []
+ * ```
  */
 export declare function pathToArray(
   path: Maybe<Readonly<Path>>,

package/jsutils/Path.js

@@ -6,8 +6,14 @@ Object.defineProperty(exports, '__esModule', {
 exports.addPath = addPath;
 exports.pathToArray = pathToArray;
 
+/** @category Paths */
+
+/** Represents a linked response path from a field back to the root response. */
+
 /**
  * Given a Path and a key, return a new Path containing the new key.
+ *
+ * @internal
  */
 function addPath(prev, key, typename) {
   return {
@@ -18,6 +24,29 @@ function addPath(prev, key, typename) {
 }
 /**
  * Given a Path, return an Array of the path keys.
+ * @param path - The linked response path to flatten.
+ * @returns An array of response path keys from root to leaf.
+ * @example
+ * ```ts
+ * import { pathToArray } from 'graphql/jsutils/Path';
+ *
+ * const path = {
+ *   prev: {
+ *     prev: {
+ *       prev: undefined,
+ *       key: 'viewer',
+ *       typename: 'Query',
+ *     },
+ *     key: 'friends',
+ *     typename: 'User',
+ *   },
+ *   key: 0,
+ *   typename: undefined,
+ * };
+ *
+ * pathToArray(path); // => ['viewer', 'friends', 0]
+ * pathToArray(undefined); // => []
+ * ```
  */
 
 function pathToArray(path) {

package/jsutils/Path.mjs

@@ -1,5 +1,11 @@
+/** @category Paths */
+
+/** Represents a linked response path from a field back to the root response. */
+
 /**
  * Given a Path and a key, return a new Path containing the new key.
+ *
+ * @internal
  */
 export function addPath(prev, key, typename) {
   return {
@@ -10,6 +16,29 @@ export function addPath(prev, key, typename) {
 }
 /**
  * Given a Path, return an Array of the path keys.
+ * @param path - The linked response path to flatten.
+ * @returns An array of response path keys from root to leaf.
+ * @example
+ * ```ts
+ * import { pathToArray } from 'graphql/jsutils/Path';
+ *
+ * const path = {
+ *   prev: {
+ *     prev: {
+ *       prev: undefined,
+ *       key: 'viewer',
+ *       typename: 'Query',
+ *     },
+ *     key: 'friends',
+ *     typename: 'User',
+ *   },
+ *   key: 0,
+ *   typename: undefined,
+ * };
+ *
+ * pathToArray(path); // => ['viewer', 'friends', 0]
+ * pathToArray(undefined); // => []
+ * ```
  */
 
 export function pathToArray(path) {

package/jsutils/PromiseOrValue.d.ts

@@ -1 +1,2 @@
+/** @internal */
 export declare type PromiseOrValue<T> = Promise<T> | T;

package/jsutils/devAssert.d.ts

@@ -1 +1,2 @@
+/** @internal */
 export declare function devAssert(condition: unknown, message: string): void;

package/jsutils/devAssert.js

@@ -5,6 +5,7 @@ Object.defineProperty(exports, '__esModule', {
 });
 exports.devAssert = devAssert;
 
+/** @internal */
 function devAssert(condition, message) {
   const booleanCondition = Boolean(condition);
 

package/jsutils/devAssert.mjs

@@ -1,3 +1,4 @@
+/** @internal */
 export function devAssert(condition, message) {
   const booleanCondition = Boolean(condition);
 

package/jsutils/didYouMean.d.ts

@@ -1,7 +1,10 @@
 /**
- * Given [ A, B, C ] return ' Did you mean A, B, or C?'.
+ * Given [A, B, C] return ' Did you mean A, B, or C?'.
+ *
+ * @internal
  */
 export declare function didYouMean(suggestions: ReadonlyArray<string>): string;
+/** @internal */
 export declare function didYouMean(
   subMessage: string,
   suggestions: ReadonlyArray<string>,

package/jsutils/didYouMean.js

@@ -6,9 +6,12 @@ Object.defineProperty(exports, '__esModule', {
 exports.didYouMean = didYouMean;
 const MAX_SUGGESTIONS = 5;
 /**
- * Given [ A, B, C ] return ' Did you mean A, B, or C?'.
+ * Given [A, B, C] return ' Did you mean A, B, or C?'.
+ *
+ * @internal
  */
 
+/** @internal */
 function didYouMean(firstArg, secondArg) {
   const [subMessage, suggestionsArg] = secondArg
     ? [firstArg, secondArg]

package/jsutils/didYouMean.mjs

@@ -1,8 +1,11 @@
 const MAX_SUGGESTIONS = 5;
 /**
- * Given [ A, B, C ] return ' Did you mean A, B, or C?'.
+ * Given [A, B, C] return ' Did you mean A, B, or C?'.
+ *
+ * @internal
  */
 
+/** @internal */
 export function didYouMean(firstArg, secondArg) {
   const [subMessage, suggestionsArg] = secondArg
     ? [firstArg, secondArg]

package/jsutils/groupBy.d.ts

@@ -1,5 +1,7 @@
 /**
  * Groups array items into a Map, given a function to produce grouping key.
+ *
+ * @internal
  */
 export declare function groupBy<K, T>(
   list: ReadonlyArray<T>,

package/jsutils/groupBy.js

@@ -7,6 +7,8 @@ exports.groupBy = groupBy;
 
 /**
  * Groups array items into a Map, given a function to produce grouping key.
+ *
+ * @internal
  */
 function groupBy(list, keyFn) {
   const result = new Map();

package/jsutils/groupBy.mjs

@@ -1,5 +1,7 @@
 /**
  * Groups array items into a Map, given a function to produce grouping key.
+ *
+ * @internal
  */
 export function groupBy(list, keyFn) {
   const result = new Map();

package/jsutils/identityFunc.d.ts

@@ -1,4 +1,6 @@
 /**
  * Returns the first argument it receives.
+ *
+ * @internal
  */
 export declare function identityFunc<T>(x: T): T;