graphql 16.14.0 → 16.14.1

package/validation/validate.js

@@ -26,12 +26,18 @@ var _specifiedRules = require('./specifiedRules.js');
 
 var _ValidationContext = require('./ValidationContext.js');
 
+/** @category Validation */
 // Per the specification, descriptions must not affect validation.
 // See https://spec.graphql.org/draft/#sec-Descriptions
 const QueryDocumentKeysToValidate = (0, _mapValue.mapValue)(
   _ast.QueryDocumentKeys,
   (keys) => keys.filter((key) => key !== 'description'),
 );
+/**
+ * Options used when validating a GraphQL document.
+ * @internal
+ */
+
 /**
  * Implements the "Validation" section of the spec.
  *
@@ -41,24 +47,76 @@ const QueryDocumentKeysToValidate = (0, _mapValue.mapValue)(
  * 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.'
+ * ```
  */
-
 function validate(
   schema,
   documentAST,
   rules = _specifiedRules.specifiedRules,
   options,
-  /** @deprecated will be removed in 17.0.0 */
+  /**
+   * 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 = new _TypeInfo.TypeInfo(schema),
 ) {
   var _options$maxErrors;
@@ -112,9 +170,7 @@ function validate(
 
   return errors;
 }
-/**
- * @internal
- */
+/** @internal */
 
 function validateSDL(
   documentAST,

package/validation/validate.mjs

@@ -1,3 +1,4 @@
+/** @category Validation */
 import { devAssert } from '../jsutils/devAssert.mjs';
 import { mapValue } from '../jsutils/mapValue.mjs';
 import { GraphQLError } from '../error/GraphQLError.mjs';
@@ -15,6 +16,11 @@ import {
 const QueryDocumentKeysToValidate = mapValue(QueryDocumentKeys, (keys) =>
   keys.filter((key) => key !== 'description'),
 );
+/**
+ * Options used when validating a GraphQL document.
+ * @internal
+ */
+
 /**
  * Implements the "Validation" section of the spec.
  *
@@ -24,24 +30,76 @@ const QueryDocumentKeysToValidate = mapValue(QueryDocumentKeys, (keys) =>
  * 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 function validate(
   schema,
   documentAST,
   rules = specifiedRules,
   options,
-  /** @deprecated will be removed in 17.0.0 */
+  /**
+   * 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 = new TypeInfo(schema),
 ) {
   var _options$maxErrors;
@@ -93,9 +151,7 @@ export function validate(
 
   return errors;
 }
-/**
- * @internal
- */
+/** @internal */
 
 export function validateSDL(
   documentAST,

package/version.d.ts

@@ -1,10 +1,7 @@
-/**
- * A string containing the version of the GraphQL.js library
- */
+/** @category Version */
+/** A string containing the version of the GraphQL.js library */
 export declare const version: string;
-/**
- * An object containing the components of the GraphQL.js version string
- */
+/** An object containing the components of the GraphQL.js version string */
 export declare const versionInfo: Readonly<{
   major: number;
   minor: number;

package/version.js

@@ -4,22 +4,20 @@ Object.defineProperty(exports, '__esModule', {
   value: true,
 });
 exports.versionInfo = exports.version = void 0;
+
+/** @category Version */
 // Note: This file is autogenerated using "resources/gen-version.js" script and
 // automatically updated by "npm version" command.
 
-/**
- * A string containing the version of the GraphQL.js library
- */
-const version = '16.14.0';
-/**
- * An object containing the components of the GraphQL.js version string
- */
+/** A string containing the version of the GraphQL.js library */
+const version = '16.14.1';
+/** An object containing the components of the GraphQL.js version string */
 
 exports.version = version;
 const versionInfo = Object.freeze({
   major: 16,
   minor: 14,
-  patch: 0,
+  patch: 1,
   preReleaseTag: null,
 });
 exports.versionInfo = versionInfo;

package/version.mjs

@@ -1,17 +1,14 @@
+/** @category Version */
 // Note: This file is autogenerated using "resources/gen-version.js" script and
 // automatically updated by "npm version" command.
 
-/**
- * A string containing the version of the GraphQL.js library
- */
-export const version = '16.14.0';
-/**
- * An object containing the components of the GraphQL.js version string
- */
+/** A string containing the version of the GraphQL.js library */
+export const version = '16.14.1';
+/** An object containing the components of the GraphQL.js version string */
 
 export const versionInfo = Object.freeze({
   major: 16,
   minor: 14,
-  patch: 0,
+  patch: 1,
   preReleaseTag: null,
 });