graphql 16.14.0 → 16.14.1

package/utilities/TypeInfo.mjs

@@ -1,3 +1,4 @@
+/** @category Type Info */
 import { isNode } from '../language/ast.mjs';
 import { Kind } from '../language/kinds.mjs';
 import { getEnterLeaveForKind } from '../language/visitor.mjs';
@@ -26,6 +27,74 @@ import { typeFromAST } from './typeFromAST.mjs';
  */
 
 export class TypeInfo {
+  /**
+   * Creates a TypeInfo instance.
+   * @param schema - Schema used for type lookups.
+   * @param initialType - Optional type to use at the start of traversal.
+   * @param getFieldDefFn - Optional field definition lookup override.
+   * @example
+   * ```ts
+   * // Track field types during a visitWithTypeInfo traversal.
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema } from 'graphql/utilities';
+   * import { TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * const seenTypes = [];
+   *
+   * visit(
+   *   parse('{ greeting }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     Field: () => {
+   *       seenTypes.push(String(typeInfo.getType()));
+   *     },
+   *   }),
+   * );
+   *
+   * seenTypes; // => ['String']
+   * ```
+   * @example
+   * ```ts
+   * // This variant starts from an initial type and supplies a field definition resolver.
+   * import { Kind } from 'graphql/language';
+   * import { GraphQLString } from 'graphql/type';
+   * import { buildSchema, TypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema, schema.getQueryType(), () => ({
+   *   name: 'virtualGreeting',
+   *   description: undefined,
+   *   type: GraphQLString,
+   *   args: [],
+   *   resolve: undefined,
+   *   subscribe: undefined,
+   *   deprecationReason: undefined,
+   *   extensions: Object.create(null),
+   *   astNode: undefined,
+   * }));
+   *
+   * typeInfo.enter({
+   *   kind: Kind.SELECTION_SET,
+   *   selections: [],
+   * });
+   * typeInfo.enter({
+   *   kind: Kind.FIELD,
+   *   name: { kind: Kind.NAME, value: 'ignored' },
+   * });
+   *
+   * typeInfo.getFieldDef()?.name; // => 'virtualGreeting'
+   * String(typeInfo.getType()); // => 'String'
+   * ```
+   */
   constructor(
     schema,
     /**
@@ -33,7 +102,11 @@ export class TypeInfo {
      *  beginning somewhere other than documents.
      */
     initialType,
-    /** @deprecated will be removed in 17.0.0 */
+    /**
+     * Deprecated field definition lookup override. Use TypeInfo's built-in
+     * field definition lookup instead because this hook will be removed in v17.
+     * @deprecated will be removed in 17.0.0
+     */
     getFieldDefFn,
   ) {
     this._schema = schema;
@@ -64,58 +137,365 @@ export class TypeInfo {
       }
     }
   }
+  /**
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
+   */
 
   get [Symbol.toStringTag]() {
     return 'TypeInfo';
   }
+  /**
+   * Returns the current output type at this point in traversal.
+   * @returns The current output type, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     viewer: User
+   *   }
+   *
+   *   type User {
+   *     name: String
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * const fieldTypes = {};
+   *
+   * visit(
+   *   parse('{ viewer { name } }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     Field: (node) => {
+   *       fieldTypes[node.name.value] = String(typeInfo.getType());
+   *     },
+   *   }),
+   * );
+   *
+   * fieldTypes; // => { viewer: 'User', name: 'String' }
+   * ```
+   */
 
   getType() {
     if (this._typeStack.length > 0) {
       return this._typeStack[this._typeStack.length - 1];
     }
   }
+  /**
+   * Returns the current parent composite type.
+   * @returns The current parent composite type, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     viewer: User
+   *   }
+   *
+   *   type User {
+   *     name: String
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * const parentTypes = {};
+   *
+   * visit(
+   *   parse('{ viewer { name } }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     Field: (node) => {
+   *       parentTypes[node.name.value] = String(typeInfo.getParentType());
+   *     },
+   *   }),
+   * );
+   *
+   * parentTypes; // => { viewer: 'Query', name: 'User' }
+   * ```
+   */
 
   getParentType() {
     if (this._parentTypeStack.length > 0) {
       return this._parentTypeStack[this._parentTypeStack.length - 1];
     }
   }
+  /**
+   * Returns the current input type at this point in traversal.
+   * @returns The current input type, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     reviews(stars: Int!, sort: Sort = NEWEST): [String]
+   *   }
+   *
+   *   enum Sort {
+   *     NEWEST
+   *     OLDEST
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * const inputTypes = {};
+   *
+   * visit(
+   *   parse('{ reviews(stars: 5, sort: OLDEST) }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     Argument: (node) => {
+   *       inputTypes[node.name.value] = String(typeInfo.getInputType());
+   *     },
+   *   }),
+   * );
+   *
+   * inputTypes; // => { stars: 'Int!', sort: 'Sort' }
+   * ```
+   */
 
   getInputType() {
     if (this._inputTypeStack.length > 0) {
       return this._inputTypeStack[this._inputTypeStack.length - 1];
     }
   }
+  /**
+   * Returns the parent input type for the current input position.
+   * @returns The parent input type, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   input ReviewFilter {
+   *     stars: Int!
+   *   }
+   *
+   *   type Query {
+   *     reviews(filter: ReviewFilter): [String]
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * const parentInputTypes = {};
+   *
+   * visit(
+   *   parse('{ reviews(filter: { stars: 5 }) }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     ObjectField: (node) => {
+   *       parentInputTypes[node.name.value] = String(typeInfo.getParentInputType());
+   *     },
+   *   }),
+   * );
+   *
+   * parentInputTypes; // => { stars: 'ReviewFilter' }
+   * ```
+   */
 
   getParentInputType() {
     if (this._inputTypeStack.length > 1) {
       return this._inputTypeStack[this._inputTypeStack.length - 2];
     }
   }
+  /**
+   * Returns the current field definition.
+   * @returns The current field definition, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * let fieldName;
+   *
+   * visit(
+   *   parse('{ greeting }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     Field: () => {
+   *       fieldName = typeInfo.getFieldDef()?.name;
+   *     },
+   *   }),
+   * );
+   *
+   * fieldName; // => 'greeting'
+   * ```
+   */
 
   getFieldDef() {
     if (this._fieldDefStack.length > 0) {
       return this._fieldDefStack[this._fieldDefStack.length - 1];
     }
   }
+  /**
+   * Returns the default value for the current input position.
+   * @returns The current default value, if one is available.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     reviews(limit: Int = 10): [String]
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * let defaultLimit;
+   *
+   * visit(
+   *   parse('{ reviews(limit: 5) }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     Argument: () => {
+   *       defaultLimit = typeInfo.getDefaultValue();
+   *     },
+   *   }),
+   * );
+   *
+   * defaultLimit; // => 10
+   * ```
+   */
 
   getDefaultValue() {
     if (this._defaultValueStack.length > 0) {
       return this._defaultValueStack[this._defaultValueStack.length - 1];
     }
   }
+  /**
+   * Returns the current directive definition.
+   * @returns The current directive definition, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * let directiveName;
+   *
+   * visit(
+   *   parse('{ greeting @include(if: true) }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     Directive: () => {
+   *       directiveName = typeInfo.getDirective()?.name;
+   *     },
+   *   }),
+   * );
+   *
+   * directiveName; // => 'include'
+   * ```
+   */
 
   getDirective() {
     return this._directive;
   }
+  /**
+   * Returns the current argument definition.
+   * @returns The current argument definition, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     reviews(limit: Int = 10): [String]
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * let argumentName;
+   *
+   * visit(
+   *   parse('{ reviews(limit: 5) }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     Argument: () => {
+   *       argumentName = typeInfo.getArgument()?.name;
+   *     },
+   *   }),
+   * );
+   *
+   * argumentName; // => 'limit'
+   * ```
+   */
 
   getArgument() {
     return this._argument;
   }
+  /**
+   * Returns the current enum value definition.
+   * @returns The current enum value definition, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   enum Sort {
+   *     NEWEST
+   *     OLDEST
+   *   }
+   *
+   *   type Query {
+   *     reviews(sort: Sort = NEWEST): [String]
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * let enumValueName;
+   *
+   * visit(
+   *   parse('{ reviews(sort: OLDEST) }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     EnumValue: () => {
+   *       enumValueName = typeInfo.getEnumValue()?.name;
+   *     },
+   *   }),
+   * );
+   *
+   * enumValueName; // => 'OLDEST'
+   * ```
+   */
 
   getEnumValue() {
     return this._enumValue;
   }
+  /**
+   * Updates this TypeInfo instance for an entered AST node.
+   * @param node - AST node being entered.
+   * @returns Nothing.
+   * @example
+   * ```ts
+   * import { Kind, parse } from 'graphql/language';
+   * import { buildSchema, TypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const document = parse('{ greeting }');
+   * const operation = document.definitions[0];
+   * const selectionSet = operation.selectionSet;
+   * const field = selectionSet.selections[0];
+   * const typeInfo = new TypeInfo(schema);
+   *
+   * typeInfo.enter(operation);
+   * typeInfo.enter(selectionSet);
+   * typeInfo.enter(field);
+   *
+   * field.kind; // => Kind.FIELD
+   * typeInfo.getParentType()?.name; // => 'Query'
+   * String(typeInfo.getType()); // => 'String'
+   * ```
+   */
 
   enter(node) {
     const schema = this._schema; // Note: many of the types below are explicitly typed as "unknown" to drop
@@ -268,6 +648,35 @@ export class TypeInfo {
       default: // Ignore other nodes
     }
   }
+  /**
+   * Updates this TypeInfo instance for a left AST node.
+   * @param node - AST node being entered.
+   * @returns Nothing.
+   * @example
+   * ```ts
+   * import { parse } from 'graphql/language';
+   * import { buildSchema, TypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const document = parse('{ greeting }');
+   * const operation = document.definitions[0];
+   * const selectionSet = operation.selectionSet;
+   * const field = selectionSet.selections[0];
+   * const typeInfo = new TypeInfo(schema);
+   *
+   * typeInfo.enter(operation);
+   * typeInfo.enter(selectionSet);
+   * typeInfo.enter(field);
+   * String(typeInfo.getType()); // => 'String'
+   *
+   * typeInfo.leave(field);
+   * typeInfo.getType(); // => undefined
+   * ```
+   */
 
   leave(node) {
     switch (node.kind) {
@@ -329,6 +738,8 @@ export class TypeInfo {
  * Not exactly the same as the executor's definition of getFieldDef, in this
  * statically evaluated environment we do not always have an Object type,
  * and need to handle Interface and Union types.
+ *
+ * @internal
  */
 function getFieldDef(schema, parentType, fieldNode) {
   const name = fieldNode.name.value;
@@ -355,6 +766,37 @@ function getFieldDef(schema, parentType, fieldNode) {
 /**
  * Creates a new visitor instance which maintains a provided TypeInfo instance
  * along with visiting visitor.
+ * @param typeInfo - TypeInfo instance to update during traversal.
+ * @param visitor - Visitor callbacks to wrap with TypeInfo updates.
+ * @returns A visitor that keeps TypeInfo in sync while delegating callbacks.
+ * @example
+ * ```ts
+ * import { parse, visit } from 'graphql/language';
+ * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ * const typeInfo = new TypeInfo(schema);
+ * const fields = [];
+ *
+ * visit(
+ *   parse('{ greeting }'),
+ *   visitWithTypeInfo(typeInfo, {
+ *     Field: (node) => {
+ *       fields.push({
+ *         name: node.name.value,
+ *         parentType: String(typeInfo.getParentType()),
+ *         type: String(typeInfo.getType()),
+ *       });
+ *     },
+ *   }),
+ * );
+ *
+ * fields; // => [{ name: 'greeting', parentType: 'Query', type: 'String' }]
+ * ```
  */
 
 export function visitWithTypeInfo(typeInfo, visitor) {

package/utilities/assertValidName.d.ts

@@ -1,11 +1,36 @@
+/** @category Validation */
 import { GraphQLError } from '../error/GraphQLError';
 /**
- * Upholds the spec rules about naming.
+ * Upholds the spec rules about naming. This deprecated helper is retained for
+ * backwards compatibility; call `assertName` instead because assertValidName
+ * will be removed in v17.
+ * @param name - The GraphQL name to validate.
+ * @returns The validated GraphQL name.
+ * @example
+ * ```ts
+ * import { assertValidName } from 'graphql/utilities';
+ *
+ * assertValidName('User'); // => 'User'
+ * assertValidName('__typename'); // throws an error
+ * ```
  * @deprecated Please use `assertName` instead. Will be removed in v17
  */
 export declare function assertValidName(name: string): string;
 /**
- * Returns an Error if a name is invalid.
+ * Returns an Error if a name is invalid. This deprecated helper is retained for
+ * backwards compatibility; call `assertName` and catch the thrown GraphQLError
+ * instead because isValidNameError will be removed in v17.
+ * @param name - The GraphQL name to validate.
+ * @returns A GraphQLError if the name is invalid; otherwise undefined.
+ * @example
+ * ```ts
+ * import { isValidNameError } from 'graphql/utilities';
+ *
+ * isValidNameError('User'); // => undefined
+ *
+ * const error = isValidNameError('__typename');
+ * error.message; // => 'Name "__typename" must not begin with "__", which is reserved by GraphQL introspection.'
+ * ```
  * @deprecated Please use `assertName` instead. Will be removed in v17
  */
 export declare function isValidNameError(

package/utilities/assertValidName.js

@@ -12,10 +12,23 @@ var _GraphQLError = require('../error/GraphQLError.js');
 
 var _assertName = require('../type/assertName.js');
 
+/** @category Validation */
+
 /* c8 ignore start */
 
 /**
- * Upholds the spec rules about naming.
+ * Upholds the spec rules about naming. This deprecated helper is retained for
+ * backwards compatibility; call `assertName` instead because assertValidName
+ * will be removed in v17.
+ * @param name - The GraphQL name to validate.
+ * @returns The validated GraphQL name.
+ * @example
+ * ```ts
+ * import { assertValidName } from 'graphql/utilities';
+ *
+ * assertValidName('User'); // => 'User'
+ * assertValidName('__typename'); // throws an error
+ * ```
  * @deprecated Please use `assertName` instead. Will be removed in v17
  */
 function assertValidName(name) {
@@ -28,7 +41,20 @@ function assertValidName(name) {
   return name;
 }
 /**
- * Returns an Error if a name is invalid.
+ * Returns an Error if a name is invalid. This deprecated helper is retained for
+ * backwards compatibility; call `assertName` and catch the thrown GraphQLError
+ * instead because isValidNameError will be removed in v17.
+ * @param name - The GraphQL name to validate.
+ * @returns A GraphQLError if the name is invalid; otherwise undefined.
+ * @example
+ * ```ts
+ * import { isValidNameError } from 'graphql/utilities';
+ *
+ * isValidNameError('User'); // => undefined
+ *
+ * const error = isValidNameError('__typename');
+ * error.message; // => 'Name "__typename" must not begin with "__", which is reserved by GraphQL introspection.'
+ * ```
  * @deprecated Please use `assertName` instead. Will be removed in v17
  */
 

package/utilities/assertValidName.mjs

@@ -1,10 +1,22 @@
+/** @category Validation */
 import { devAssert } from '../jsutils/devAssert.mjs';
 import { GraphQLError } from '../error/GraphQLError.mjs';
 import { assertName } from '../type/assertName.mjs';
 /* c8 ignore start */
 
 /**
- * Upholds the spec rules about naming.
+ * Upholds the spec rules about naming. This deprecated helper is retained for
+ * backwards compatibility; call `assertName` instead because assertValidName
+ * will be removed in v17.
+ * @param name - The GraphQL name to validate.
+ * @returns The validated GraphQL name.
+ * @example
+ * ```ts
+ * import { assertValidName } from 'graphql/utilities';
+ *
+ * assertValidName('User'); // => 'User'
+ * assertValidName('__typename'); // throws an error
+ * ```
  * @deprecated Please use `assertName` instead. Will be removed in v17
  */
 
@@ -18,7 +30,20 @@ export function assertValidName(name) {
   return name;
 }
 /**
- * Returns an Error if a name is invalid.
+ * Returns an Error if a name is invalid. This deprecated helper is retained for
+ * backwards compatibility; call `assertName` and catch the thrown GraphQLError
+ * instead because isValidNameError will be removed in v17.
+ * @param name - The GraphQL name to validate.
+ * @returns A GraphQLError if the name is invalid; otherwise undefined.
+ * @example
+ * ```ts
+ * import { isValidNameError } from 'graphql/utilities';
+ *
+ * isValidNameError('User'); // => undefined
+ *
+ * const error = isValidNameError('__typename');
+ * error.message; // => 'Name "__typename" must not begin with "__", which is reserved by GraphQL introspection.'
+ * ```
  * @deprecated Please use `assertName` instead. Will be removed in v17
  */