graphql 16.14.0 → 16.14.1

package/language/visitor.mjs

@@ -1,12 +1,11 @@
+/** @category Visiting */
 import { devAssert } from '../jsutils/devAssert.mjs';
 import { inspect } from '../jsutils/inspect.mjs';
 import { isNode, QueryDocumentKeys } from './ast.mjs';
 import { Kind } from './kinds.mjs';
-/**
- * A visitor is provided to visit, it contains the collection of
- * relevant functions to be called during the visitor's traversal.
- */
+/** A visitor defines the callbacks called during AST traversal. */
 
+/** A value that can be returned from a visitor function to stop traversal. */
 export const BREAK = Object.freeze({});
 /**
  * visit() will walk through an AST using a depth-first traversal, calling
@@ -21,72 +20,94 @@ export const BREAK = Object.freeze({});
  * When using visit() to edit an AST, the original AST will not be modified, and
  * a new version of the AST with the changes applied will be returned from the
  * visit function.
- *
+ * @param root - The AST node at which to start traversal.
+ * @param visitor - The visitor or reducer functions to call while traversing.
+ * @param visitorKeys - Optional map of child keys to visit for each AST node kind.
+ * @returns The original AST, an edited AST, or a reduced value depending on the visitor.
+ * @typeParam N - The root AST node type returned when visiting without reducing.
+ * @example
  * ```ts
- * const editedAST = visit(ast, {
- *   enter(node, key, parent, path, ancestors) {
- *     // @return
- *     //   undefined: no action
- *     //   false: skip visiting this node
- *     //   visitor.BREAK: stop visiting altogether
- *     //   null: delete this node
- *     //   any value: replace this node with the returned value
+ * // Return values control traversal: undefined makes no change, false skips
+ * // a subtree, BREAK stops traversal, null removes a node, and any other
+ * // value replaces the current node.
+ * import { Kind, parse, print, visit } from 'graphql/language';
+ *
+ * const document = parse('{ hero { name } }');
+ * const editedAST = visit(document, {
+ *   Field: (node) => {
+ *     if (node.name.value === 'hero') {
+ *       return {
+ *         ...node,
+ *         name: { kind: Kind.NAME, value: 'human' },
+ *       };
+ *     }
  *   },
- *   leave(node, key, parent, path, ancestors) {
- *     // @return
- *     //   undefined: no action
- *     //   false: no action
- *     //   visitor.BREAK: stop visiting altogether
- *     //   null: delete this node
- *     //   any value: replace this node with the returned value
- *   }
  * });
+ *
+ * print(editedAST); // => '{\n  human {\n    name\n  }\n}'
  * ```
+ * @example
+ * ```ts
+ * // A named visitor function runs when entering nodes of that kind.
+ * import { parse, visit } from 'graphql/language';
  *
- * Alternatively to providing enter() and leave() functions, a visitor can
- * instead provide functions named the same as the kinds of AST nodes, or
- * enter/leave visitors at a named key, leading to three permutations of the
- * visitor API:
+ * const document = parse('{ hero { name } }');
+ * const fieldNames = [];
  *
- * 1) Named visitors triggered when entering a node of a specific kind.
+ * visit(document, {
+ *   Field: (node) => {
+ *     fieldNames.push(node.name.value);
+ *   },
+ * });
  *
- * ```ts
- * visit(ast, {
- *   Kind(node) {
- *     // enter the "Kind" node
- *   }
- * })
+ * fieldNames; // => ['hero', 'name']
  * ```
+ * @example
+ * ```ts
+ * // A named visitor object can provide separate enter and leave handlers for
+ * // nodes of that kind.
+ * import { parse, visit } from 'graphql/language';
  *
- * 2) Named visitors that trigger upon entering and leaving a node of a specific kind.
+ * const document = parse('{ hero { name } }');
+ * const events = [];
  *
- * ```ts
- * visit(ast, {
- *   Kind: {
- *     enter(node) {
- *       // enter the "Kind" node
- *     }
- *     leave(node) {
- *       // leave the "Kind" node
- *     }
- *   }
- * })
+ * visit(document, {
+ *   Field: {
+ *     enter: (node) => {
+ *       events.push(`enter:${node.name.value}`);
+ *     },
+ *     leave: (node) => {
+ *       events.push(`leave:${node.name.value}`);
+ *     },
+ *   },
+ * });
+ *
+ * events; // => ['enter:hero', 'enter:name', 'leave:name', 'leave:hero']
  * ```
+ * @example
+ * ```ts
+ * // Generic enter and leave handlers run for every node.
+ * import { parse, visit } from 'graphql/language';
  *
- * 3) Generic visitors that trigger upon entering and leaving any node.
+ * const document = parse('{ hero { name } }');
+ * let enterCount = 0;
+ * let leaveCount = 0;
  *
- * ```ts
- * visit(ast, {
- *   enter(node) {
- *     // enter any node
+ * visit(document, {
+ *   enter: (node) => {
+ *     enterCount += 1;
+ *   },
+ *   leave: (node) => {
+ *     leaveCount += 1;
  *   },
- *   leave(node) {
- *     // leave any node
- *   }
- * })
+ * });
+ *
+ * enterCount; // => leaveCount
+ * enterCount > 0; // => true
  * ```
  */
 
+/** @internal */
 export function visit(root, visitor, visitorKeys = QueryDocumentKeys) {
   const enterLeaveMap = new Map();
 
@@ -246,6 +267,25 @@ export function visit(root, visitor, visitorKeys = QueryDocumentKeys) {
  * parallel. Each visitor will be visited for each node before moving on.
  *
  * If a prior visitor edits a node, no following visitors will see that node.
+ * @param visitors - The visitors to merge into one parallel visitor.
+ * @returns A visitor that delegates traversal to each provided visitor.
+ * @example
+ * ```ts
+ * import { parse, visit, visitInParallel } from 'graphql/language';
+ *
+ * const document = parse('{ hero { name } }');
+ * const events = [];
+ *
+ * visit(
+ *   document,
+ *   visitInParallel([
+ *     { Field: (node) => { events.push(`field:${node.name.value}`); } },
+ *     { Name: (node) => { events.push(`name:${node.value}`); } },
+ *   ]),
+ * );
+ *
+ * events; // => ['field:hero', 'name:hero', 'field:name', 'name:name']
+ * ```
  */
 
 export function visitInParallel(visitors) {
@@ -322,6 +362,18 @@ export function visitInParallel(visitors) {
 }
 /**
  * Given a visitor instance and a node kind, return EnterLeaveVisitor for that kind.
+ * @param visitor - The visitor object to inspect.
+ * @param kind - The AST node kind to resolve handlers for.
+ * @returns The enter and leave handlers that apply for the given node kind.
+ * @example
+ * ```ts
+ * import { Kind, getEnterLeaveForKind } from 'graphql/language';
+ *
+ * const handlers = getEnterLeaveForKind({ Field: () => {} }, Kind.FIELD);
+ *
+ * typeof handlers.enter; // => 'function'
+ * handlers.leave; // => undefined
+ * ```
  */
 
 export function getEnterLeaveForKind(visitor, kind) {
@@ -345,8 +397,24 @@ export function getEnterLeaveForKind(visitor, kind) {
 }
 /**
  * Given a visitor instance, if it is leaving or not, and a node kind, return
- * the function the visitor runtime should call.
+ * the function the visitor runtime should call. This deprecated compatibility
+ * helper delegates to `getEnterLeaveForKind`; call `getEnterLeaveForKind`
+ * directly because getVisitFn will be removed in v17.
+ * @param visitor - The visitor object to inspect.
+ * @param kind - The AST node kind to resolve a handler for.
+ * @param isLeaving - Whether to resolve the leave handler instead of the enter handler.
+ * @returns The visit function that applies for the given node kind and traversal phase, if one exists.
+ * @example
+ * ```ts
+ * import { Kind, getVisitFn } from 'graphql/language';
  *
+ * const enter = getVisitFn({ Field: () => {} }, Kind.FIELD, false);
+ * const leave = getVisitFn({ Field: () => {} }, Kind.FIELD, true);
+ *
+ * typeof enter; // => 'function'
+ * leave; // => undefined
+ * ```
+ * @category Visiting
  * @deprecated Please use `getEnterLeaveForKind` instead. Will be removed in v17
  */
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphql",
-  "version": "16.14.0",
+  "version": "16.14.1",
   "description": "A Query Language and Runtime which can target any service.",
   "license": "MIT",
   "main": "index",

package/subscription/index.d.ts

@@ -5,15 +5,21 @@
  *
  * For backwards compatibility, the `graphql/subscription` module
  * currently re-exports the moved functions from the `graphql/execution`
- * module. In the next major release, the `graphql/subscription` module
- * will be dropped entirely.
+ * module. In v17, the `graphql/subscription` module will be dropped entirely.
+ *
+ * These exports are also available from the root `graphql` package.
+ * @packageDocumentation
+ * @category Subscriptions
  */
 import type { ExecutionArgs } from '../execution/execute';
 /**
- * @deprecated use ExecutionArgs instead. Will be removed in v17
+ * Deprecated legacy alias for ExecutionArgs retained by the subscription
+ * module. Use `ExecutionArgs` directly instead because SubscriptionArgs will be
+ * removed in v17.
  *
  * ExecutionArgs has been broadened to include all properties within SubscriptionArgs.
  * The SubscriptionArgs type is retained for backwards compatibility.
+ * @deprecated use ExecutionArgs instead. Will be removed in v17
  */
 export interface SubscriptionArgs extends ExecutionArgs {}
 export { subscribe, createSourceEventStream } from '../execution/subscribe';

package/subscription/index.mjs

@@ -5,15 +5,21 @@
  *
  * For backwards compatibility, the `graphql/subscription` module
  * currently re-exports the moved functions from the `graphql/execution`
- * module. In the next major release, the `graphql/subscription` module
- * will be dropped entirely.
+ * module. In v17, the `graphql/subscription` module will be dropped entirely.
+ *
+ * These exports are also available from the root `graphql` package.
+ * @packageDocumentation
+ * @category Subscriptions
  */
 
 /**
- * @deprecated use ExecutionArgs instead. Will be removed in v17
+ * Deprecated legacy alias for ExecutionArgs retained by the subscription
+ * module. Use `ExecutionArgs` directly instead because SubscriptionArgs will be
+ * removed in v17.
  *
  * ExecutionArgs has been broadened to include all properties within SubscriptionArgs.
  * The SubscriptionArgs type is retained for backwards compatibility.
+ * @deprecated use ExecutionArgs instead. Will be removed in v17
  */
 // eslint-disable-next-line @typescript-eslint/no-empty-interface
 export { subscribe, createSourceEventStream } from '../execution/subscribe.mjs';

package/type/assertName.d.ts

@@ -1,10 +1,27 @@
+/** @category Names */
 /**
  * Upholds the spec rules about naming.
+ * @param name - The GraphQL name to validate.
+ * @returns The validated GraphQL name.
+ * @example
+ * ```ts
+ * import { assertName } from 'graphql/type';
+ *
+ * assertName('User'); // => 'User'
+ * assertName('123User'); // throws an error
+ * ```
  */
 export declare function assertName(name: string): string;
 /**
  * Upholds the spec rules about naming enum values.
+ * @param name - The GraphQL name to validate.
+ * @returns The validated GraphQL name.
+ * @example
+ * ```ts
+ * import { assertEnumValueName } from 'graphql/type';
  *
- * @internal
+ * assertEnumValueName('ACTIVE'); // => 'ACTIVE'
+ * assertEnumValueName('true'); // throws an error
+ * ```
  */
 export declare function assertEnumValueName(name: string): string;

package/type/assertName.js

@@ -12,8 +12,19 @@ var _GraphQLError = require('../error/GraphQLError.js');
 
 var _characterClasses = require('../language/characterClasses.js');
 
+/** @category Names */
+
 /**
  * Upholds the spec rules about naming.
+ * @param name - The GraphQL name to validate.
+ * @returns The validated GraphQL name.
+ * @example
+ * ```ts
+ * import { assertName } from 'graphql/type';
+ *
+ * assertName('User'); // => 'User'
+ * assertName('123User'); // throws an error
+ * ```
  */
 function assertName(name) {
   name != null || (0, _devAssert.devAssert)(false, 'Must provide name.');
@@ -44,8 +55,15 @@ function assertName(name) {
 }
 /**
  * Upholds the spec rules about naming enum values.
+ * @param name - The GraphQL name to validate.
+ * @returns The validated GraphQL name.
+ * @example
+ * ```ts
+ * import { assertEnumValueName } from 'graphql/type';
  *
- * @internal
+ * assertEnumValueName('ACTIVE'); // => 'ACTIVE'
+ * assertEnumValueName('true'); // throws an error
+ * ```
  */
 
 function assertEnumValueName(name) {

package/type/assertName.mjs

@@ -1,8 +1,18 @@
+/** @category Names */
 import { devAssert } from '../jsutils/devAssert.mjs';
 import { GraphQLError } from '../error/GraphQLError.mjs';
 import { isNameContinue, isNameStart } from '../language/characterClasses.mjs';
 /**
  * Upholds the spec rules about naming.
+ * @param name - The GraphQL name to validate.
+ * @returns The validated GraphQL name.
+ * @example
+ * ```ts
+ * import { assertName } from 'graphql/type';
+ *
+ * assertName('User'); // => 'User'
+ * assertName('123User'); // throws an error
+ * ```
  */
 
 export function assertName(name) {
@@ -31,8 +41,15 @@ export function assertName(name) {
 }
 /**
  * Upholds the spec rules about naming enum values.
+ * @param name - The GraphQL name to validate.
+ * @returns The validated GraphQL name.
+ * @example
+ * ```ts
+ * import { assertEnumValueName } from 'graphql/type';
  *
- * @internal
+ * assertEnumValueName('ACTIVE'); // => 'ACTIVE'
+ * assertEnumValueName('true'); // throws an error
+ * ```
  */
 
 export function assertEnumValueName(name) {