graphql 16.14.0 → 16.14.1

package/validation/ValidationContext.mjs

@@ -1,3 +1,4 @@
+/** @category Validation Context */
 import { Kind } from '../language/kinds.mjs';
 import { visit } from '../language/visitor.mjs';
 import { TypeInfo, visitWithTypeInfo } from '../utilities/TypeInfo.mjs';
@@ -6,6 +7,8 @@ import { TypeInfo, visitWithTypeInfo } from '../utilities/TypeInfo.mjs';
  * An instance of this class is passed as the "this" context to all validators,
  * allowing access to commonly useful contextual information from within a
  * validation rule.
+ *
+ * @internal
  */
 export class ASTValidationContext {
   constructor(ast, onError) {
@@ -103,6 +106,9 @@ export class ASTValidationContext {
     return fragments;
   }
 }
+/** @internal */
+
+/** @internal */
 export class SDLValidationContext extends ASTValidationContext {
   constructor(ast, schema, onError) {
     super(ast, onError);
@@ -117,7 +123,43 @@ export class SDLValidationContext extends ASTValidationContext {
     return this._schema;
   }
 }
+/** @internal */
+
+/** Validation context passed to query validation rules. */
 export class ValidationContext extends ASTValidationContext {
+  /**
+   * Creates a ValidationContext instance.
+   * @param schema - Schema used to validate the document.
+   * @param ast - Document AST being validated.
+   * @param typeInfo - TypeInfo instance used to track traversal state.
+   * @param onError - Callback invoked for each validation error.
+   * @example
+   * ```ts
+   * import { parse } from 'graphql/language';
+   * import { GraphQLError } from 'graphql/error';
+   * import { buildSchema, TypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const document = parse('{ greeting }');
+   * const errors = [];
+   * const context = new ValidationContext(
+   *   schema,
+   *   document,
+   *   new TypeInfo(schema),
+   *   (error) => errors.push(error),
+   * );
+   *
+   * context.reportError(new GraphQLError('Example validation error.'));
+   *
+   * context.getSchema(); // => schema
+   * errors[0].message; // => 'Example validation error.'
+   * ```
+   */
   constructor(schema, ast, typeInfo, onError) {
     super(ast, onError);
     this._schema = schema;
@@ -125,14 +167,72 @@ export class ValidationContext extends ASTValidationContext {
     this._variableUsages = new Map();
     this._recursiveVariableUsages = new Map();
   }
+  /**
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
+   */
 
   get [Symbol.toStringTag]() {
     return 'ValidationContext';
   }
+  /**
+   * Returns the schema being used by this validation context.
+   * @returns The schema being validated against.
+   * @example
+   * ```ts
+   * import { parse } from 'graphql/language';
+   * import { buildSchema, TypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const context = new ValidationContext(
+   *   schema,
+   *   parse('{ greeting }'),
+   *   new TypeInfo(schema),
+   *   () => {},
+   * );
+   *
+   * context.getSchema().getQueryType()?.name; // => 'Query'
+   * ```
+   */
 
   getSchema() {
     return this._schema;
   }
+  /**
+   * Returns variable usages found directly within this node.
+   * @param node - The AST node to inspect or visit.
+   * @returns Variable usages found directly within this node.
+   * @example
+   * ```ts
+   * import { parse } from 'graphql/language';
+   * import { buildSchema, TypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting(name: String): String
+   *   }
+   * `);
+   * const document = parse('query ($name: String) { greeting(name: $name) }');
+   * const operation = document.definitions[0];
+   * const context = new ValidationContext(
+   *   schema,
+   *   document,
+   *   new TypeInfo(schema),
+   *   () => {},
+   * );
+   *
+   * const usages = context.getVariableUsages(operation);
+   *
+   * usages[0].node.name.value; // => 'name'
+   * String(usages[0].type); // => 'String'
+   * ```
+   */
 
   getVariableUsages(node) {
     let usages = this._variableUsages.get(node);
@@ -162,6 +262,49 @@ export class ValidationContext extends ASTValidationContext {
 
     return usages;
   }
+  /**
+   * Returns variable usages for an operation, including variables used by referenced fragments.
+   * @param operation - Operation definition to inspect.
+   * @returns Variable usages reachable from the operation.
+   * @example
+   * ```ts
+   * import { parse } from 'graphql/language';
+   * import { buildSchema, TypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     viewer: User
+   *   }
+   *
+   *   type User {
+   *     name(prefix: String): String
+   *   }
+   * `);
+   * const document = parse(`
+   *   query ($prefix: String) {
+   *     viewer {
+   *       ...UserName
+   *     }
+   *   }
+   *
+   *   fragment UserName on User {
+   *     name(prefix: $prefix)
+   *   }
+   * `);
+   * const operation = document.definitions[0];
+   * const context = new ValidationContext(
+   *   schema,
+   *   document,
+   *   new TypeInfo(schema),
+   *   () => {},
+   * );
+   *
+   * const usages = context.getRecursiveVariableUsages(operation);
+   *
+   * usages.map((usage) => usage.node.name.value); // => ['prefix']
+   * ```
+   */
 
   getRecursiveVariableUsages(operation) {
     let usages = this._recursiveVariableUsages.get(operation);
@@ -178,36 +321,294 @@ export class ValidationContext extends ASTValidationContext {
 
     return usages;
   }
+  /**
+   * 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';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const document = parse('{ greeting }');
+   * const typeInfo = new TypeInfo(schema);
+   * const context = new ValidationContext(schema, document, typeInfo, () => {});
+   * let typeName;
+   *
+   * visit(
+   *   document,
+   *   visitWithTypeInfo(typeInfo, {
+   *     Field: () => {
+   *       typeName = String(context.getType());
+   *     },
+   *   }),
+   * );
+   *
+   * typeName; // => 'String'
+   * ```
+   */
 
   getType() {
     return this._typeInfo.getType();
   }
+  /**
+   * 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';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const document = parse('{ greeting }');
+   * const typeInfo = new TypeInfo(schema);
+   * const context = new ValidationContext(schema, document, typeInfo, () => {});
+   * let parentTypeName;
+   *
+   * visit(
+   *   document,
+   *   visitWithTypeInfo(typeInfo, {
+   *     Field: () => {
+   *       parentTypeName = context.getParentType()?.name;
+   *     },
+   *   }),
+   * );
+   *
+   * parentTypeName; // => 'Query'
+   * ```
+   */
 
   getParentType() {
     return this._typeInfo.getParentType();
   }
+  /**
+   * 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';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     reviews(limit: Int): [String]
+   *   }
+   * `);
+   * const document = parse('{ reviews(limit: 5) }');
+   * const typeInfo = new TypeInfo(schema);
+   * const context = new ValidationContext(schema, document, typeInfo, () => {});
+   * let inputTypeName;
+   *
+   * visit(
+   *   document,
+   *   visitWithTypeInfo(typeInfo, {
+   *     Argument: () => {
+   *       inputTypeName = String(context.getInputType());
+   *     },
+   *   }),
+   * );
+   *
+   * inputTypeName; // => 'Int'
+   * ```
+   */
 
   getInputType() {
     return this._typeInfo.getInputType();
   }
+  /**
+   * 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';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   input ReviewFilter {
+   *     stars: Int
+   *   }
+   *
+   *   type Query {
+   *     reviews(filter: ReviewFilter): [String]
+   *   }
+   * `);
+   * const document = parse('{ reviews(filter: { stars: 5 }) }');
+   * const typeInfo = new TypeInfo(schema);
+   * const context = new ValidationContext(schema, document, typeInfo, () => {});
+   * let parentInputTypeName;
+   *
+   * visit(
+   *   document,
+   *   visitWithTypeInfo(typeInfo, {
+   *     ObjectField: () => {
+   *       parentInputTypeName = String(context.getParentInputType());
+   *     },
+   *   }),
+   * );
+   *
+   * parentInputTypeName; // => 'ReviewFilter'
+   * ```
+   */
 
   getParentInputType() {
     return this._typeInfo.getParentInputType();
   }
+  /**
+   * 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';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const document = parse('{ greeting }');
+   * const typeInfo = new TypeInfo(schema);
+   * const context = new ValidationContext(schema, document, typeInfo, () => {});
+   * let fieldName;
+   *
+   * visit(
+   *   document,
+   *   visitWithTypeInfo(typeInfo, {
+   *     Field: () => {
+   *       fieldName = context.getFieldDef()?.name;
+   *     },
+   *   }),
+   * );
+   *
+   * fieldName; // => 'greeting'
+   * ```
+   */
 
   getFieldDef() {
     return this._typeInfo.getFieldDef();
   }
+  /**
+   * 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';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const document = parse('{ greeting @include(if: true) }');
+   * const typeInfo = new TypeInfo(schema);
+   * const context = new ValidationContext(schema, document, typeInfo, () => {});
+   * let directiveName;
+   *
+   * visit(
+   *   document,
+   *   visitWithTypeInfo(typeInfo, {
+   *     Directive: () => {
+   *       directiveName = context.getDirective()?.name;
+   *     },
+   *   }),
+   * );
+   *
+   * directiveName; // => 'include'
+   * ```
+   */
 
   getDirective() {
     return this._typeInfo.getDirective();
   }
+  /**
+   * 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';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     reviews(limit: Int): [String]
+   *   }
+   * `);
+   * const document = parse('{ reviews(limit: 5) }');
+   * const typeInfo = new TypeInfo(schema);
+   * const context = new ValidationContext(schema, document, typeInfo, () => {});
+   * let argumentName;
+   *
+   * visit(
+   *   document,
+   *   visitWithTypeInfo(typeInfo, {
+   *     Argument: () => {
+   *       argumentName = context.getArgument()?.name;
+   *     },
+   *   }),
+   * );
+   *
+   * argumentName; // => 'limit'
+   * ```
+   */
 
   getArgument() {
     return this._typeInfo.getArgument();
   }
+  /**
+   * 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';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   enum Sort {
+   *     NEWEST
+   *     OLDEST
+   *   }
+   *
+   *   type Query {
+   *     reviews(sort: Sort): [String]
+   *   }
+   * `);
+   * const document = parse('{ reviews(sort: OLDEST) }');
+   * const typeInfo = new TypeInfo(schema);
+   * const context = new ValidationContext(schema, document, typeInfo, () => {});
+   * let enumValueName;
+   *
+   * visit(
+   *   document,
+   *   visitWithTypeInfo(typeInfo, {
+   *     EnumValue: () => {
+   *       enumValueName = context.getEnumValue()?.name;
+   *     },
+   *   }),
+   * );
+   *
+   * enumValueName; // => 'OLDEST'
+   * ```
+   */
 
   getEnumValue() {
     return this._typeInfo.getEnumValue();
   }
 }
+/** A function that creates an AST visitor for validating a GraphQL document. */

package/validation/index.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Validate GraphQL documents and schemas with the specified validation rules.
+ *
+ * These exports are also available from the root `graphql` package.
+ * @packageDocumentation
+ */
 export { validate } from './validate';
 export { ValidationContext } from './ValidationContext';
 export type { ValidationRule } from './ValidationContext';

package/validation/index.mjs

@@ -1,3 +1,9 @@
+/**
+ * Validate GraphQL documents and schemas with the specified validation rules.
+ *
+ * These exports are also available from the root `graphql` package.
+ * @packageDocumentation
+ */
 export { validate } from './validate.mjs';
 export { ValidationContext } from './ValidationContext.mjs';
 // All validation rules in the GraphQL Specification.

package/validation/rules/ExecutableDefinitionsRule.d.ts

@@ -1,3 +1,4 @@
+/** @category Validation Rules */
 import type { ASTVisitor } from '../../language/visitor';
 import type { ASTValidationContext } from '../ValidationContext';
 /**
@@ -7,6 +8,33 @@ import type { ASTValidationContext } from '../ValidationContext';
  * operation or fragment definitions.
  *
  * See https://spec.graphql.org/draft/#sec-Executable-Definitions
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { ExecutableDefinitionsRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   type Extra { field: String }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [ExecutableDefinitionsRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { name }
+ * `);
+ * const validErrors = validate(schema, validDocument, [ExecutableDefinitionsRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
 export declare function ExecutableDefinitionsRule(
   context: ASTValidationContext,

package/validation/rules/ExecutableDefinitionsRule.js

@@ -11,6 +11,8 @@ var _kinds = require('../../language/kinds.js');
 
 var _predicates = require('../../language/predicates.js');
 
+/** @category Validation Rules */
+
 /**
  * Executable definitions
  *
@@ -18,6 +20,33 @@ var _predicates = require('../../language/predicates.js');
  * operation or fragment definitions.
  *
  * See https://spec.graphql.org/draft/#sec-Executable-Definitions
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { ExecutableDefinitionsRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   type Extra { field: String }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [ExecutableDefinitionsRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { name }
+ * `);
+ * const validErrors = validate(schema, validDocument, [ExecutableDefinitionsRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
 function ExecutableDefinitionsRule(context) {
   return {

package/validation/rules/ExecutableDefinitionsRule.mjs

@@ -1,3 +1,4 @@
+/** @category Validation Rules */
 import { GraphQLError } from '../../error/GraphQLError.mjs';
 import { Kind } from '../../language/kinds.mjs';
 import { isExecutableDefinitionNode } from '../../language/predicates.mjs';
@@ -9,6 +10,33 @@ import { isExecutableDefinitionNode } from '../../language/predicates.mjs';
  * operation or fragment definitions.
  *
  * See https://spec.graphql.org/draft/#sec-Executable-Definitions
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { ExecutableDefinitionsRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   type Extra { field: String }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [ExecutableDefinitionsRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { name }
+ * `);
+ * const validErrors = validate(schema, validDocument, [ExecutableDefinitionsRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
 export function ExecutableDefinitionsRule(context) {
   return {

package/validation/rules/FieldsOnCorrectTypeRule.d.ts

@@ -1,3 +1,4 @@
+/** @category Validation Rules */
 import type { ASTVisitor } from '../../language/visitor';
 import type { ValidationContext } from '../ValidationContext';
 /**
@@ -7,6 +8,33 @@ import type { ValidationContext } from '../ValidationContext';
  * parent type, or are an allowed meta field such as __typename.
  *
  * See https://spec.graphql.org/draft/#sec-Field-Selections
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { FieldsOnCorrectTypeRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { missing }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [FieldsOnCorrectTypeRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { name }
+ * `);
+ * const validErrors = validate(schema, validDocument, [FieldsOnCorrectTypeRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
 export declare function FieldsOnCorrectTypeRule(
   context: ValidationContext,