graphql 17.0.0-beta.1 → 17.0.0-beta.2

package/type/validate.d.mts

@@ -1,3 +1,4 @@
+/** @category Validation */
 import type { Maybe } from "../jsutils/Maybe.mjs";
 import { GraphQLError } from "../error/GraphQLError.mjs";
 import type { GraphQLDefaultInput, GraphQLInputType } from "./definition.mjs";
@@ -8,14 +9,42 @@ import type { GraphQLSchema } from "./schema.mjs";
  *
  * Validation runs synchronously, returning an array of encountered errors, or
  * an empty array if no errors were encountered and the Schema is valid.
+ * @param schema - GraphQL schema to use.
+ * @returns Schema validation errors, or an empty array when the schema is valid.
+ * @example
+ * ```ts
+ * import { validateSchema } from 'graphql/type';
+ * import { buildSchema } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ * const errors = validateSchema(schema);
+ *
+ * errors; // => []
+ * ```
  */
 export declare function validateSchema(schema: GraphQLSchema): ReadonlyArray<GraphQLError>;
 /**
  * Utility function which asserts a schema is valid by throwing an error if
  * it is invalid.
+ * @param schema - GraphQL schema to use.
+ * @example
+ * ```ts
+ * import { assertValidSchema } from 'graphql/type';
+ * import { buildSchema } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * assertValidSchema(schema); // does not throw
+ * ```
  */
 export declare function assertValidSchema(schema: GraphQLSchema): void;
-/**
- * @internal
- */
+/** @internal */
 export declare function validateDefaultInput(defaultInput: GraphQLDefaultInput, inputType: GraphQLInputType, onError: (error: GraphQLError, path: ReadonlyArray<string | number>) => void, hideSuggestions?: Maybe<boolean>): void;

package/type/validate.d.ts

@@ -1,3 +1,4 @@
+/** @category Validation */
 import type { Maybe } from "../jsutils/Maybe.js";
 import { GraphQLError } from "../error/GraphQLError.js";
 import type { GraphQLDefaultInput, GraphQLInputType } from "./definition.js";
@@ -8,14 +9,42 @@ import type { GraphQLSchema } from "./schema.js";
  *
  * Validation runs synchronously, returning an array of encountered errors, or
  * an empty array if no errors were encountered and the Schema is valid.
+ * @param schema - GraphQL schema to use.
+ * @returns Schema validation errors, or an empty array when the schema is valid.
+ * @example
+ * ```ts
+ * import { validateSchema } from 'graphql/type';
+ * import { buildSchema } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ * const errors = validateSchema(schema);
+ *
+ * errors; // => []
+ * ```
  */
 export declare function validateSchema(schema: GraphQLSchema): ReadonlyArray<GraphQLError>;
 /**
  * Utility function which asserts a schema is valid by throwing an error if
  * it is invalid.
+ * @param schema - GraphQL schema to use.
+ * @example
+ * ```ts
+ * import { assertValidSchema } from 'graphql/type';
+ * import { buildSchema } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * assertValidSchema(schema); // does not throw
+ * ```
  */
 export declare function assertValidSchema(schema: GraphQLSchema): void;
-/**
- * @internal
- */
+/** @internal */
 export declare function validateDefaultInput(defaultInput: GraphQLDefaultInput, inputType: GraphQLInputType, onError: (error: GraphQLError, path: ReadonlyArray<string | number>) => void, hideSuggestions?: Maybe<boolean>): void;

package/type/validate.js

@@ -22,35 +22,19 @@ const definition_ts_1 = require("./definition.js");
 const directives_ts_1 = require("./directives.js");
 const introspection_ts_1 = require("./introspection.js");
 const schema_ts_1 = require("./schema.js");
-/**
- * Implements the "Type Validation" sub-sections of the specification's
- * "Type System" section.
- *
- * Validation runs synchronously, returning an array of encountered errors, or
- * an empty array if no errors were encountered and the Schema is valid.
- */
 function validateSchema(schema) {
-    // First check to ensure the provided value is in fact a GraphQLSchema.
     (0, schema_ts_1.assertSchema)(schema);
-    // If this Schema has already been validated, return the previous results.
     if (schema.__validationErrors) {
         return schema.__validationErrors;
     }
-    // Validate the schema, producing a list of errors.
     const context = new SchemaValidationContext(schema);
     validateRootTypes(context);
     validateDirectives(context);
     validateTypes(context);
-    // Persist the results of validation before returning to ensure validation
-    // does not run multiple times for this schema.
     const errors = context.getErrors();
     schema.__validationErrors = errors;
     return errors;
 }
-/**
- * Utility function which asserts a schema is valid by throwing an error if
- * it is invalid.
- */
 function assertValidSchema(schema) {
     const errors = validateSchema(schema);
     if (errors.length !== 0) {
@@ -108,21 +92,16 @@ function getOperationTypeNode(schema, operation) {
 }
 function validateDirectives(context) {
     for (const directive of context.schema.getDirectives()) {
-        // Ensure all directives are in fact GraphQL directives.
         if (!(0, directives_ts_1.isDirective)(directive)) {
             context.reportError(`Expected directive but got: ${(0, inspect_ts_1.inspect)(directive)}.`, directive?.astNode);
             continue;
         }
-        // Ensure they are named correctly.
         validateName(context, directive);
         if (directive.locations.length === 0) {
             context.reportError(`Directive ${directive} must include 1 or more locations.`, directive.astNode);
         }
-        // Ensure the arguments are valid.
         for (const arg of directive.args) {
-            // Ensure they are named correctly.
             validateName(context, arg);
-            // Ensure the type is an input type.
             if (!(0, definition_ts_1.isInputType)(arg.type)) {
                 context.reportError(`The type of ${arg} must be Input Type ` +
                     `but got: ${(0, inspect_ts_1.inspect)(arg.type)}.`, arg.astNode);
@@ -150,9 +129,6 @@ function validateDefaultValue(context, inputValue) {
         return;
     }
     if (!defaultInput.literal) {
-        // If there were validation errors, check to see if it can be "uncoerced"
-        // and then correctly validated. If so, report a clear error with a path
-        // to resolution.
         try {
             const uncoercedValue = uncoerceDefaultValue(defaultInput.value, inputValue.type);
             const uncoercedErrors = [];
@@ -165,17 +141,12 @@ function validateDefaultValue(context, inputValue) {
             }
         }
         catch (_error) {
-            // ignore
         }
     }
-    // Otherwise report the original set of errors.
     for (const [error, path] of errors) {
         context.reportError(`${inputValue} has invalid default value${(0, printPathArray_ts_1.printPathArray)(path)}: ${error.message}`, error.nodes ?? inputValue.astNode?.defaultValue);
     }
 }
-/**
- * @internal
- */
 function validateDefaultInput(defaultInput, inputType, onError, hideSuggestions) {
     if (defaultInput.literal) {
         (0, validateInputValue_ts_1.validateInputLiteral)(defaultInput.literal, inputType, onError, undefined, undefined, hideSuggestions);
@@ -183,15 +154,6 @@ function validateDefaultInput(defaultInput, inputType, onError, hideSuggestions)
     }
     (0, validateInputValue_ts_1.validateInputValue)(defaultInput.value, inputType, onError, hideSuggestions);
 }
-/**
- * Historically GraphQL.js allowed default values to be provided as
- * assumed-coerced "internal" values, however default values should be provided
- * as "external" pre-coerced values. `uncoerceDefaultValue()` will convert such
- * "internal" values to "external" values to display as part of validation.
- *
- * This performs the "opposite" of `coerceInputValue()`. Given an "internal"
- * coerced value, reverse the process to provide an "external" uncoerced value.
- */
 function uncoerceDefaultValue(value, type) {
     if ((0, definition_ts_1.isNonNullType)(type)) {
         return uncoerceDefaultValue(value, type.ofType);
@@ -216,67 +178,48 @@ function uncoerceDefaultValue(value, type) {
         });
     }
     (0, definition_ts_1.assertLeafType)(type);
-    // For most leaf types (Scalars, Enums), output value coercion ("serialize") is
-    // the inverse of input coercion ("parseValue") and will produce an
-    // "external" value. Historically, this method was also used as part of the
-    // now-deprecated "astFromValue" to perform the same behavior.
     return type.coerceOutputValue(value);
 }
 function validateName(context, node) {
-    // Ensure names are valid, however introspection types opt out.
     if (node.name.startsWith('__')) {
         context.reportError(`Name "${node.name}" must not begin with "__", which is reserved by GraphQL introspection.`, node.astNode);
     }
 }
 function validateTypes(context) {
-    // Ensure Input Objects do not contain non-nullable circular references.
     const validateInputObjectNonNullCircularRefs = createInputObjectNonNullCircularRefsValidator(context);
     const validateInputObjectDefaultValueCircularRefs = createInputObjectDefaultValueCircularRefsValidator(context);
     const typeMap = context.schema.getTypeMap();
     for (const type of Object.values(typeMap)) {
-        // Ensure all provided types are in fact GraphQL type.
         if (!(0, definition_ts_1.isNamedType)(type)) {
             context.reportError(`Expected GraphQL named type but got: ${(0, inspect_ts_1.inspect)(type)}.`, type.astNode);
             continue;
         }
-        // Ensure it is named correctly (excluding introspection types).
         if (!(0, introspection_ts_1.isIntrospectionType)(type)) {
             validateName(context, type);
         }
         if ((0, definition_ts_1.isObjectType)(type)) {
-            // Ensure fields are valid
             validateFields(context, type);
-            // Ensure objects implement the interfaces they claim to.
             validateInterfaces(context, type);
         }
         else if ((0, definition_ts_1.isInterfaceType)(type)) {
-            // Ensure fields are valid.
             validateFields(context, type);
-            // Ensure interfaces implement the interfaces they claim to.
             validateInterfaces(context, type);
         }
         else if ((0, definition_ts_1.isUnionType)(type)) {
-            // Ensure Unions include valid member types.
             validateUnionMembers(context, type);
         }
         else if ((0, definition_ts_1.isEnumType)(type)) {
-            // Ensure Enums have valid values.
             validateEnumValues(context, type);
         }
         else if ((0, definition_ts_1.isInputObjectType)(type)) {
-            // Ensure Input Object fields are valid.
             validateInputFields(context, type);
-            // Ensure Input Objects do not contain invalid field circular references.
-            // Ensure Input Objects do not contain non-nullable circular references.
             validateInputObjectNonNullCircularRefs(type);
-            // Ensure Input Objects do not contain invalid default value circular references.
             validateInputObjectDefaultValueCircularRefs(type);
         }
     }
 }
 function validateFields(context, type) {
     const fields = Object.values(type.getFields());
-    // Objects and Interfaces both must define one or more fields.
     if (fields.length === 0) {
         context.reportError(`Type ${type} must define one or more fields.`, [
             type.astNode,
@@ -284,18 +227,13 @@ function validateFields(context, type) {
         ]);
     }
     for (const field of fields) {
-        // Ensure they are named correctly.
         validateName(context, field);
-        // Ensure the type is an output type
         if (!(0, definition_ts_1.isOutputType)(field.type)) {
             context.reportError(`The type of ${field} must be Output Type ` +
                 `but got: ${(0, inspect_ts_1.inspect)(field.type)}.`, field.astNode?.type);
         }
-        // Ensure the arguments are valid
         for (const arg of field.args) {
-            // Ensure they are named correctly.
             validateName(context, arg);
-            // Ensure the type is an input type
             if (!(0, definition_ts_1.isInputType)(arg.type)) {
                 context.reportError(`The type of ${arg} must be Input Type but got: ${(0, inspect_ts_1.inspect)(arg.type)}.`, arg.astNode?.type);
             }
@@ -332,37 +270,27 @@ function validateInterfaces(context, type) {
 }
 function validateTypeImplementsInterface(context, type, iface) {
     const typeFieldMap = type.getFields();
-    // Assert each interface field is implemented.
     for (const ifaceField of Object.values(iface.getFields())) {
         const typeField = typeFieldMap[ifaceField.name];
-        // Assert interface field exists on type.
         if (typeField == null) {
             context.reportError(`Interface field ${ifaceField} expected but ${type} does not provide it.`, [ifaceField.astNode, type.astNode, ...type.extensionASTNodes]);
             continue;
         }
-        // Assert interface field type is satisfied by type field type, by being
-        // a valid subtype. (covariant)
         if (!(0, typeComparators_ts_1.isTypeSubTypeOf)(context.schema, typeField.type, ifaceField.type)) {
             context.reportError(`Interface field ${ifaceField} expects type ${ifaceField.type} ` +
                 `but ${typeField} is type ${typeField.type}.`, [ifaceField.astNode?.type, typeField.astNode?.type]);
         }
-        // Assert each interface field arg is implemented.
         for (const ifaceArg of ifaceField.args) {
             const typeArg = typeField.args.find((arg) => arg.name === ifaceArg.name);
-            // Assert interface field arg exists on object field.
             if (!typeArg) {
                 context.reportError(`Interface field argument ${ifaceArg} expected but ${typeField} does not provide it.`, [ifaceArg.astNode, typeField.astNode]);
                 continue;
             }
-            // Assert interface field arg type matches object field arg type.
-            // (invariant)
-            // TODO: change to contravariant?
             if (!(0, typeComparators_ts_1.isEqualType)(ifaceArg.type, typeArg.type)) {
                 context.reportError(`Interface field argument ${ifaceArg} expects type ${ifaceArg.type} ` +
                     `but ${typeArg} is type ${typeArg.type}.`, [ifaceArg.astNode?.type, typeArg.astNode?.type]);
             }
         }
-        // Assert additional arguments must not be required.
         for (const typeArg of typeField.args) {
             if ((0, definition_ts_1.isRequiredArgument)(typeArg)) {
                 const ifaceArg = ifaceField.args.find((arg) => arg.name === typeArg.name);
@@ -372,7 +300,6 @@ function validateTypeImplementsInterface(context, type, iface) {
                 }
             }
         }
-        // Asserts that field is not deprecated unless interface field is
         if (typeField.deprecationReason != null &&
             ifaceField.deprecationReason == null) {
             context.reportError(`Interface field ${iface.name}.${ifaceField.name} is not deprecated, so ` +
@@ -420,7 +347,6 @@ function validateEnumValues(context, enumType) {
         context.reportError(`Enum type ${enumType} must define one or more values.`, [enumType.astNode, ...enumType.extensionASTNodes]);
     }
     for (const enumValue of enumValues) {
-        // Ensure valid name.
         validateName(context, enumValue);
     }
 }
@@ -429,11 +355,8 @@ function validateInputFields(context, inputObj) {
     if (fields.length === 0) {
         context.reportError(`Input Object type ${inputObj} must define one or more fields.`, [inputObj.astNode, ...inputObj.extensionASTNodes]);
     }
-    // Ensure the input fields are valid
     for (const field of fields) {
-        // Ensure they are named correctly.
         validateName(context, field);
-        // Ensure the type is an input type
         if (!(0, definition_ts_1.isInputType)(field.type)) {
             context.reportError(`The type of ${field} must be Input Type ` +
                 `but got: ${(0, inspect_ts_1.inspect)(field.type)}.`, field.astNode?.type);
@@ -456,18 +379,10 @@ function validateOneOfInputObjectField(type, field, context) {
     }
 }
 function createInputObjectNonNullCircularRefsValidator(context) {
-    // Modified copy of algorithm from 'src/validation/rules/NoFragmentCycles.js'.
-    // Tracks already visited types to maintain O(N) and to ensure that cycles
-    // are not redundantly reported.
     const visitedTypes = new Set();
-    // Array of types nodes used to produce meaningful errors
     const fieldPath = [];
-    // Position in the type path
     const fieldPathIndexByTypeName = Object.create(null);
     return detectCycleRecursive;
-    // This does a straight-forward DFS to find cycles.
-    // It does not terminate when a cycle was found but continues to explore
-    // the graph to find all possible cycles.
     function detectCycleRecursive(inputObj) {
         if (visitedTypes.has(inputObj)) {
             return;
@@ -502,25 +417,13 @@ function createInputObjectNonNullCircularRefsValidator(context) {
     }
 }
 function createInputObjectDefaultValueCircularRefsValidator(context) {
-    // Modified copy of algorithm from 'src/validation/rules/NoFragmentCycles.js'.
-    // Tracks already visited types to maintain O(N) and to ensure that cycles
-    // are not redundantly reported.
     const visitedFields = Object.create(null);
-    // Array of keys for fields and default values used to produce meaningful errors.
     const fieldPath = [];
-    // Position in the path
     const fieldPathIndex = Object.create(null);
-    // This does a straight-forward DFS to find cycles.
-    // It does not terminate when a cycle was found but continues to explore
-    // the graph to find all possible cycles.
     return function validateInputObjectDefaultValueCircularRefs(inputObj) {
-        // Start with an empty object as a way to visit every field in this input
-        // object type and apply every default value.
         return detectValueDefaultValueCycle(inputObj, Object.create(null));
     };
     function detectValueDefaultValueCycle(inputObj, defaultValue) {
-        // If the value is a List, recursively check each entry for a cycle.
-        // Otherwise, only object values can contain a cycle.
         if ((0, isIterableObject_ts_1.isIterableObject)(defaultValue)) {
             for (const itemValue of defaultValue) {
                 detectValueDefaultValueCycle(inputObj, itemValue);
@@ -530,27 +433,20 @@ function createInputObjectDefaultValueCircularRefsValidator(context) {
         else if (!(0, isObjectLike_ts_1.isObjectLike)(defaultValue)) {
             return;
         }
-        // Check each defined field for a cycle.
         for (const field of Object.values(inputObj.getFields())) {
             const namedFieldType = (0, definition_ts_1.getNamedType)(field.type);
-            // Only input object type fields can result in a cycle.
             if (!(0, definition_ts_1.isInputObjectType)(namedFieldType)) {
                 continue;
             }
             if (Object.hasOwn(defaultValue, field.name)) {
-                // If the provided value has this field defined, recursively check it
-                // for cycles.
                 detectValueDefaultValueCycle(namedFieldType, defaultValue[field.name]);
             }
             else {
-                // Otherwise check this field's default value for cycles.
                 detectFieldDefaultValueCycle(field, namedFieldType, `${inputObj}.${field.name}`);
             }
         }
     }
     function detectLiteralDefaultValueCycle(inputObj, defaultValue) {
-        // If the value is a List, recursively check each entry for a cycle.
-        // Otherwise, only object values can contain a cycle.
         if (defaultValue.kind === kinds_ts_1.Kind.LIST) {
             for (const itemLiteral of defaultValue.values) {
                 detectLiteralDefaultValueCycle(inputObj, itemLiteral);
@@ -560,32 +456,25 @@ function createInputObjectDefaultValueCircularRefsValidator(context) {
         else if (defaultValue.kind !== kinds_ts_1.Kind.OBJECT) {
             return;
         }
-        // Check each defined field for a cycle.
         const fieldNodes = (0, keyMap_ts_1.keyMap)(defaultValue.fields, (field) => field.name.value);
         for (const field of Object.values(inputObj.getFields())) {
             const namedFieldType = (0, definition_ts_1.getNamedType)(field.type);
-            // Only input object type fields can result in a cycle.
             if (!(0, definition_ts_1.isInputObjectType)(namedFieldType)) {
                 continue;
             }
             if (Object.hasOwn(fieldNodes, field.name)) {
-                // If the provided value has this field defined, recursively check it
-                // for cycles.
                 detectLiteralDefaultValueCycle(namedFieldType, fieldNodes[field.name].value);
             }
             else {
-                // Otherwise check this field's default value for cycles.
                 detectFieldDefaultValueCycle(field, namedFieldType, `${inputObj}.${field.name}`);
             }
         }
     }
     function detectFieldDefaultValueCycle(field, fieldType, fieldStr) {
-        // Only a field with a default value can result in a cycle.
         const defaultInput = field.default;
         if (defaultInput === undefined) {
             return;
         }
-        // Check to see if there is cycle.
         const cycleIndex = fieldPathIndex[fieldStr];
         if (cycleIndex !== undefined) {
             context.reportError(`Invalid circular reference. The default value of Input Object field ${fieldStr} references itself${cycleIndex < fieldPath.length
@@ -596,7 +485,6 @@ function createInputObjectDefaultValueCircularRefsValidator(context) {
                 : ''}.`, fieldPath.slice(cycleIndex - 1).map(([, node]) => node));
             return;
         }
-        // Recurse into this field's default value once, tracking the path.
         if (visitedFields[fieldStr] === undefined) {
             visitedFields[fieldStr] = true;
             fieldPathIndex[fieldStr] = fieldPath.push([