graphql 16.14.0 → 16.14.1

package/validation/rules/VariablesAreInputTypesRule.mjs

@@ -1,3 +1,4 @@
+/** @category Validation Rules */
 import { GraphQLError } from '../../error/GraphQLError.mjs';
 import { print } from '../../language/printer.mjs';
 import { isInputType } from '../../type/definition.mjs';
@@ -10,6 +11,37 @@ import { typeFromAST } from '../../utilities/typeFromAST.mjs';
  * input types (scalar, enum, or input object).
  *
  * See https://spec.graphql.org/draft/#sec-Variables-Are-Input-Types
+ * @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 { VariablesAreInputTypesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     field(arg: ID): String
+ *   }
+ *
+ *   type User {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   query ($user: User) { field(arg: "1") }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [VariablesAreInputTypesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   query ($id: ID) { field(arg: $id) }
+ * `);
+ * const validErrors = validate(schema, validDocument, [VariablesAreInputTypesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
 export function VariablesAreInputTypesRule(context) {
   return {

package/validation/rules/VariablesInAllowedPositionRule.d.ts

@@ -1,3 +1,4 @@
+/** @category Validation Rules */
 import type { ASTVisitor } from '../../language/visitor';
 import type { ValidationContext } from '../ValidationContext';
 /**
@@ -6,6 +7,33 @@ import type { ValidationContext } from '../ValidationContext';
  * Variable usages must be compatible with the arguments they are passed to.
  *
  * See https://spec.graphql.org/draft/#sec-All-Variable-Usages-are-Allowed
+ * @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 { VariablesInAllowedPositionRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     field(arg: ID!): String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   query ($id: String) { field(arg: $id) }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [VariablesInAllowedPositionRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   query ($id: ID!) { field(arg: $id) }
+ * `);
+ * const validErrors = validate(schema, validDocument, [VariablesInAllowedPositionRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
 export declare function VariablesInAllowedPositionRule(
   context: ValidationContext,

package/validation/rules/VariablesInAllowedPositionRule.js

@@ -17,12 +17,41 @@ var _typeComparators = require('../../utilities/typeComparators.js');
 
 var _typeFromAST = require('../../utilities/typeFromAST.js');
 
+/** @category Validation Rules */
+
 /**
  * Variables in allowed position
  *
  * Variable usages must be compatible with the arguments they are passed to.
  *
  * See https://spec.graphql.org/draft/#sec-All-Variable-Usages-are-Allowed
+ * @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 { VariablesInAllowedPositionRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     field(arg: ID!): String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   query ($id: String) { field(arg: $id) }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [VariablesInAllowedPositionRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   query ($id: ID!) { field(arg: $id) }
+ * `);
+ * const validErrors = validate(schema, validDocument, [VariablesInAllowedPositionRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
 function VariablesInAllowedPositionRule(context) {
   let varDefMap = Object.create(null);
@@ -96,8 +125,13 @@ function VariablesInAllowedPositionRule(context) {
 }
 /**
  * Returns true if the variable is allowed in the location it was found,
- * which includes considering if default values exist for either the variable
+ * including considering if default values exist for either the variable
  * or the location at which it is located.
+ *
+ * OneOf Input Object Type fields are considered separately above to
+ * provide a more descriptive error message.
+ *
+ * @internal
  */
 
 function allowedVariableUsage(

package/validation/rules/VariablesInAllowedPositionRule.mjs

@@ -1,3 +1,4 @@
+/** @category Validation Rules */
 import { inspect } from '../../jsutils/inspect.mjs';
 import { GraphQLError } from '../../error/GraphQLError.mjs';
 import { Kind } from '../../language/kinds.mjs';
@@ -15,6 +16,33 @@ import { typeFromAST } from '../../utilities/typeFromAST.mjs';
  * Variable usages must be compatible with the arguments they are passed to.
  *
  * See https://spec.graphql.org/draft/#sec-All-Variable-Usages-are-Allowed
+ * @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 { VariablesInAllowedPositionRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     field(arg: ID!): String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   query ($id: String) { field(arg: $id) }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [VariablesInAllowedPositionRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   query ($id: ID!) { field(arg: $id) }
+ * `);
+ * const validErrors = validate(schema, validDocument, [VariablesInAllowedPositionRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
 export function VariablesInAllowedPositionRule(context) {
   let varDefMap = Object.create(null);
@@ -88,8 +116,13 @@ export function VariablesInAllowedPositionRule(context) {
 }
 /**
  * Returns true if the variable is allowed in the location it was found,
- * which includes considering if default values exist for either the variable
+ * including considering if default values exist for either the variable
  * or the location at which it is located.
+ *
+ * OneOf Input Object Type fields are considered separately above to
+ * provide a more descriptive error message.
+ *
+ * @internal
  */
 
 function allowedVariableUsage(

package/validation/rules/custom/NoDeprecatedCustomRule.d.ts

@@ -1,3 +1,4 @@
+/** @category Custom Rules */
 import type { ASTVisitor } from '../../../language/visitor';
 import type { ValidationContext } from '../../ValidationContext';
 /**
@@ -9,6 +10,46 @@ import type { ValidationContext } from '../../ValidationContext';
  * Note: This rule is optional and is not part of the Validation section of the GraphQL
  * Specification. The main purpose of this rule is detection of deprecated usages and not
  * necessarily to forbid their use when querying a service.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import {
+ *   GraphQLObjectType,
+ *   GraphQLSchema,
+ *   GraphQLString,
+ *   parse,
+ *   validate,
+ * } from 'graphql';
+ * import { NoDeprecatedCustomRule } from 'graphql/validation';
+ *
+ * const schema = new GraphQLSchema({
+ *   query: new GraphQLObjectType({
+ *     name: 'Query',
+ *     fields: {
+ *       name: { type: GraphQLString },
+ *       oldName: {
+ *         type: GraphQLString,
+ *         deprecationReason: 'Use name instead.',
+ *       },
+ *     },
+ *   }),
+ * });
+ *
+ * const invalidDocument = parse(`
+ *   { oldName }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [NoDeprecatedCustomRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { name }
+ * `);
+ * const validErrors = validate(schema, validDocument, [NoDeprecatedCustomRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
 export declare function NoDeprecatedCustomRule(
   context: ValidationContext,

package/validation/rules/custom/NoDeprecatedCustomRule.js

@@ -11,6 +11,8 @@ var _GraphQLError = require('../../../error/GraphQLError.js');
 
 var _definition = require('../../../type/definition.js');
 
+/** @category Custom Rules */
+
 /**
  * No deprecated
  *
@@ -20,6 +22,46 @@ var _definition = require('../../../type/definition.js');
  * Note: This rule is optional and is not part of the Validation section of the GraphQL
  * Specification. The main purpose of this rule is detection of deprecated usages and not
  * necessarily to forbid their use when querying a service.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import {
+ *   GraphQLObjectType,
+ *   GraphQLSchema,
+ *   GraphQLString,
+ *   parse,
+ *   validate,
+ * } from 'graphql';
+ * import { NoDeprecatedCustomRule } from 'graphql/validation';
+ *
+ * const schema = new GraphQLSchema({
+ *   query: new GraphQLObjectType({
+ *     name: 'Query',
+ *     fields: {
+ *       name: { type: GraphQLString },
+ *       oldName: {
+ *         type: GraphQLString,
+ *         deprecationReason: 'Use name instead.',
+ *       },
+ *     },
+ *   }),
+ * });
+ *
+ * const invalidDocument = parse(`
+ *   { oldName }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [NoDeprecatedCustomRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { name }
+ * `);
+ * const validErrors = validate(schema, validDocument, [NoDeprecatedCustomRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
 function NoDeprecatedCustomRule(context) {
   return {

package/validation/rules/custom/NoDeprecatedCustomRule.mjs

@@ -1,3 +1,4 @@
+/** @category Custom Rules */
 import { invariant } from '../../../jsutils/invariant.mjs';
 import { GraphQLError } from '../../../error/GraphQLError.mjs';
 import { getNamedType, isInputObjectType } from '../../../type/definition.mjs';
@@ -11,6 +12,46 @@ import { getNamedType, isInputObjectType } from '../../../type/definition.mjs';
  * Note: This rule is optional and is not part of the Validation section of the GraphQL
  * Specification. The main purpose of this rule is detection of deprecated usages and not
  * necessarily to forbid their use when querying a service.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import {
+ *   GraphQLObjectType,
+ *   GraphQLSchema,
+ *   GraphQLString,
+ *   parse,
+ *   validate,
+ * } from 'graphql';
+ * import { NoDeprecatedCustomRule } from 'graphql/validation';
+ *
+ * const schema = new GraphQLSchema({
+ *   query: new GraphQLObjectType({
+ *     name: 'Query',
+ *     fields: {
+ *       name: { type: GraphQLString },
+ *       oldName: {
+ *         type: GraphQLString,
+ *         deprecationReason: 'Use name instead.',
+ *       },
+ *     },
+ *   }),
+ * });
+ *
+ * const invalidDocument = parse(`
+ *   { oldName }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [NoDeprecatedCustomRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { name }
+ * `);
+ * const validErrors = validate(schema, validDocument, [NoDeprecatedCustomRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
 export function NoDeprecatedCustomRule(context) {
   return {

package/validation/rules/custom/NoSchemaIntrospectionCustomRule.d.ts

@@ -1,3 +1,4 @@
+/** @category Custom Rules */
 import type { ASTVisitor } from '../../../language/visitor';
 import type { ValidationContext } from '../../ValidationContext';
 /**
@@ -9,6 +10,33 @@ import type { ValidationContext } from '../../ValidationContext';
  * Note: This rule is optional and is not part of the Validation section of the
  * GraphQL Specification. This rule effectively disables introspection, which
  * does not reflect best practices and should only be done if absolutely necessary.
+ * @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 { NoSchemaIntrospectionCustomRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { __schema { queryType { name } } }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [NoSchemaIntrospectionCustomRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { name }
+ * `);
+ * const validErrors = validate(schema, validDocument, [NoSchemaIntrospectionCustomRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
 export declare function NoSchemaIntrospectionCustomRule(
   context: ValidationContext,

package/validation/rules/custom/NoSchemaIntrospectionCustomRule.js

@@ -11,6 +11,8 @@ var _definition = require('../../../type/definition.js');
 
 var _introspection = require('../../../type/introspection.js');
 
+/** @category Custom Rules */
+
 /**
  * Prohibit introspection queries
  *
@@ -20,6 +22,33 @@ var _introspection = require('../../../type/introspection.js');
  * Note: This rule is optional and is not part of the Validation section of the
  * GraphQL Specification. This rule effectively disables introspection, which
  * does not reflect best practices and should only be done if absolutely necessary.
+ * @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 { NoSchemaIntrospectionCustomRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { __schema { queryType { name } } }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [NoSchemaIntrospectionCustomRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { name }
+ * `);
+ * const validErrors = validate(schema, validDocument, [NoSchemaIntrospectionCustomRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
 function NoSchemaIntrospectionCustomRule(context) {
   return {

package/validation/rules/custom/NoSchemaIntrospectionCustomRule.mjs

@@ -1,3 +1,4 @@
+/** @category Custom Rules */
 import { GraphQLError } from '../../../error/GraphQLError.mjs';
 import { getNamedType } from '../../../type/definition.mjs';
 import { isIntrospectionType } from '../../../type/introspection.mjs';
@@ -11,6 +12,33 @@ import { isIntrospectionType } from '../../../type/introspection.mjs';
  * Note: This rule is optional and is not part of the Validation section of the
  * GraphQL Specification. This rule effectively disables introspection, which
  * does not reflect best practices and should only be done if absolutely necessary.
+ * @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 { NoSchemaIntrospectionCustomRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { __schema { queryType { name } } }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [NoSchemaIntrospectionCustomRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { name }
+ * `);
+ * const validErrors = validate(schema, validDocument, [NoSchemaIntrospectionCustomRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
 export function NoSchemaIntrospectionCustomRule(context) {
   return {

package/validation/specifiedRules.d.ts

@@ -1,3 +1,4 @@
+/** @category Validation Rules */
 import { MaxIntrospectionDepthRule } from './rules/MaxIntrospectionDepthRule';
 import type { SDLValidationRule, ValidationRule } from './ValidationContext';
 /**
@@ -12,7 +13,5 @@ export declare const recommendedRules: readonly typeof MaxIntrospectionDepthRule
  * most clear output when encountering multiple validation errors.
  */
 export declare const specifiedRules: ReadonlyArray<ValidationRule>;
-/**
- * @internal
- */
+/** @internal */
 export declare const specifiedSDLRules: ReadonlyArray<SDLValidationRule>;

package/validation/specifiedRules.js

@@ -78,6 +78,7 @@ var _VariablesAreInputTypesRule = require('./rules/VariablesAreInputTypesRule.js
 
 var _VariablesInAllowedPositionRule = require('./rules/VariablesInAllowedPositionRule.js');
 
+/** @category Validation Rules */
 // Spec Section: "Executable Definitions"
 // Spec Section: "Field Selections on Objects, Interfaces, and Unions Types"
 // Spec Section: "Fragments on Composite Types"
@@ -151,9 +152,7 @@ const specifiedRules = Object.freeze([
   _UniqueInputFieldNamesRule.UniqueInputFieldNamesRule,
   ...recommendedRules,
 ]);
-/**
- * @internal
- */
+/** @internal */
 
 exports.specifiedRules = specifiedRules;
 const specifiedSDLRules = Object.freeze([

package/validation/specifiedRules.mjs

@@ -1,3 +1,4 @@
+/** @category Validation Rules */
 // Spec Section: "Executable Definitions"
 import { ExecutableDefinitionsRule } from './rules/ExecutableDefinitionsRule.mjs'; // Spec Section: "Field Selections on Objects, Interfaces, and Unions Types"
 
@@ -109,9 +110,7 @@ export const specifiedRules = Object.freeze([
   UniqueInputFieldNamesRule,
   ...recommendedRules,
 ]);
-/**
- * @internal
- */
+/** @internal */
 
 export const specifiedSDLRules = Object.freeze([
   LoneSchemaDefinitionRule,

package/validation/validate.d.ts

@@ -1,9 +1,21 @@
+/** @category Validation */
 import type { Maybe } from '../jsutils/Maybe';
 import { GraphQLError } from '../error/GraphQLError';
 import type { DocumentNode } from '../language/ast';
 import type { GraphQLSchema } from '../type/schema';
 import { TypeInfo } from '../utilities/TypeInfo';
 import type { SDLValidationRule, ValidationRule } from './ValidationContext';
+/**
+ * Options used when validating a GraphQL document.
+ * @internal
+ */
+export interface ValidationOptions {
+  /**
+   * Maximum number of validation errors before validation stops.
+   * @internal
+   */
+  maxErrors?: number;
+}
 /**
  * Implements the "Validation" section of the spec.
  *
@@ -13,30 +25,79 @@ import type { SDLValidationRule, ValidationRule } from './ValidationContext';
  * A list of specific validation rules may be provided. If not provided, the
  * default list of rules defined by the GraphQL specification will be used.
  *
- * Each validation rules is a function which returns a visitor
+ * Each validation rule is a function that returns a visitor
  * (see the language/visitor API). Visitor methods are expected to return
  * GraphQLErrors, or Arrays of GraphQLErrors when invalid.
  *
  * Validate will stop validation after a `maxErrors` limit has been reached.
  * Attackers can send pathologically invalid queries to induce a DoS attack,
- * so by default `maxErrors` set to 100 errors.
+ * so `maxErrors` defaults to 100 errors.
  *
  * Optionally a custom TypeInfo instance may be provided. If not provided, one
  * will be created from the provided schema.
+ * @param schema - Schema to validate against.
+ * @param documentAST - Document AST to validate.
+ * @param rules - Validation rules to apply.
+ * @param options - Validation options, including error limits.
+ * @param typeInfo - TypeInfo instance to update during traversal.
+ * @returns Validation errors, or an empty array when the document is valid.
+ * @example
+ * ```ts
+ * // Validate with the default specified rules.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { validate } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ *
+ * validate(schema, parse('{ greeting }')); // => []
+ *
+ * const errors = validate(schema, parse('{ missing }'));
+ * errors[0].message; // => 'Cannot query field "missing" on type "Query".'
+ * ```
+ * @example
+ * ```ts
+ * // This variant uses a custom rule list, TypeInfo, and validation options.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema, TypeInfo } from 'graphql/utilities';
+ * import { FieldsOnCorrectTypeRule, validate } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ * const document = parse('{ missingOne missingTwo }');
+ *
+ * const errors = validate(
+ *   schema,
+ *   document,
+ *   [FieldsOnCorrectTypeRule],
+ *   { maxErrors: 1 },
+ *   new TypeInfo(schema),
+ * );
+ *
+ * errors.length; // => 2
+ * errors[1].message; // => 'Too many validation errors, error limit reached. Validation aborted.'
+ * ```
  */
 export declare function validate(
   schema: GraphQLSchema,
   documentAST: DocumentNode,
   rules?: ReadonlyArray<ValidationRule>,
-  options?: {
-    maxErrors?: number;
-  },
-  /** @deprecated will be removed in 17.0.0 */
+  options?: ValidationOptions,
+  /**
+   * Deprecated TypeInfo instance used to track traversal state during
+   * validation. Omit this argument so validate creates the TypeInfo instance.
+   * @deprecated will be removed in 17.0.0
+   */
   typeInfo?: TypeInfo,
 ): ReadonlyArray<GraphQLError>;
-/**
- * @internal
- */
+/** @internal */
 export declare function validateSDL(
   documentAST: DocumentNode,
   schemaToExtend?: Maybe<GraphQLSchema>,