graphql 17.0.0-beta.0 → 17.0.0-beta.2

package/validation/ValidationContext.d.ts

@@ -1,12 +1,13 @@
-import type { Maybe } from '../jsutils/Maybe.js';
-import type { GraphQLError } from '../error/GraphQLError.js';
-import type { DocumentNode, FragmentDefinitionNode, FragmentSpreadNode, OperationDefinitionNode, SelectionSetNode, VariableDefinitionNode, VariableNode } from '../language/ast.js';
-import type { ASTVisitor } from '../language/visitor.js';
-import type { GraphQLArgument, GraphQLCompositeType, GraphQLEnumValue, GraphQLField, GraphQLInputType, GraphQLOutputType } from '../type/definition.js';
-import type { GraphQLDirective } from '../type/directives.js';
-import type { GraphQLSchema } from '../type/schema.js';
-import type { FragmentSignature } from '../utilities/TypeInfo.js';
-import { TypeInfo } from '../utilities/TypeInfo.js';
+/** @category Validation Context */
+import type { Maybe } from "../jsutils/Maybe.js";
+import type { GraphQLError } from "../error/GraphQLError.js";
+import type { DocumentNode, FragmentDefinitionNode, FragmentSpreadNode, OperationDefinitionNode, SelectionSetNode, VariableDefinitionNode, VariableNode } from "../language/ast.js";
+import type { ASTVisitor } from "../language/visitor.js";
+import type { GraphQLArgument, GraphQLCompositeType, GraphQLEnumValue, GraphQLField, GraphQLInputType, GraphQLOutputType } from "../type/definition.js";
+import type { GraphQLDirective } from "../type/directives.js";
+import type { GraphQLSchema } from "../type/schema.js";
+import type { FragmentSignature } from "../utilities/TypeInfo.js";
+import { TypeInfo } from "../utilities/TypeInfo.js";
 type NodeWithSelectionSet = OperationDefinitionNode | FragmentDefinitionNode;
 interface VariableUsage {
     readonly node: VariableNode;
@@ -19,6 +20,8 @@ interface VariableUsage {
  * 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 declare class ASTValidationContext {
     private _ast;
@@ -34,7 +37,9 @@ export declare class ASTValidationContext {
     getFragmentSpreads(node: SelectionSetNode): ReadonlyArray<FragmentSpreadNode>;
     getRecursivelyReferencedFragments(operation: OperationDefinitionNode): ReadonlyArray<FragmentDefinitionNode>;
 }
+/** @internal */
 export type ASTValidationRule = (context: ASTValidationContext) => ASTVisitor;
+/** @internal */
 export declare class SDLValidationContext extends ASTValidationContext {
     private _schema;
     constructor(ast: DocumentNode, schema: Maybe<GraphQLSchema>, onError: (error: GraphQLError) => void);
@@ -42,29 +47,514 @@ export declare class SDLValidationContext extends ASTValidationContext {
     get [Symbol.toStringTag](): string;
     getSchema(): Maybe<GraphQLSchema>;
 }
+/** @internal */
 export type SDLValidationRule = (context: SDLValidationContext) => ASTVisitor;
+/** Validation context passed to query validation rules. */
 export declare class ValidationContext extends ASTValidationContext {
     private _schema;
     private _typeInfo;
     private _variableUsages;
     private _recursiveVariableUsages;
     private _hideSuggestions;
+    /**
+     * 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.
+     * @param hideSuggestions - Whether suggestion text should be omitted from errors.
+     * @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: GraphQLSchema, ast: DocumentNode, typeInfo: TypeInfo, onError: (error: GraphQLError) => void, hideSuggestions?: Maybe<boolean>);
+    /**
+     * Returns the value used by `Object.prototype.toString`.
+     * @returns The built-in string tag for this object.
+     */
     get [Symbol.toStringTag](): string;
+    /**
+     * Returns whether validation error suggestions are hidden.
+     * @returns True when suggestion text should be omitted from errors.
+     */
     get hideSuggestions(): boolean;
+    /**
+     * 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(): GraphQLSchema;
+    /**
+     * 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: NodeWithSelectionSet): ReadonlyArray<VariableUsage>;
+    /**
+     * 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: OperationDefinitionNode): ReadonlyArray<VariableUsage>;
+    /**
+     * 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(): Maybe<GraphQLOutputType>;
+    /**
+     * 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(): Maybe<GraphQLCompositeType>;
+    /**
+     * 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(): Maybe<GraphQLInputType>;
+    /**
+     * 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(): Maybe<GraphQLInputType>;
+    /**
+     * 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(): Maybe<GraphQLField<unknown, unknown>>;
+    /**
+     * 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(): Maybe<GraphQLDirective>;
+    /**
+     * 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(): Maybe<GraphQLArgument>;
+    /**
+     * Returns the fragment signature at the current traversal position.
+     * @returns The current fragment signature, if one is active.
+     * @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(
+     *   `
+     *     {
+     *       ...GreetingFields
+     *     }
+     *
+     *     fragment GreetingFields on Query {
+     *       greeting
+     *     }
+     *   `,
+     *   { experimentalFragmentArguments: true },
+     * );
+     * const typeInfo = new TypeInfo(schema);
+     * const context = new ValidationContext(schema, document, typeInfo, () => {});
+     * let fragmentName;
+     *
+     * visit(
+     *   document,
+     *   visitWithTypeInfo(typeInfo, {
+     *     FragmentSpread: () => {
+     *       fragmentName = context.getFragmentSignature()?.definition.name.value;
+     *     },
+     *   }),
+     * );
+     *
+     * fragmentName; // => 'GreetingFields'
+     * ```
+     */
     getFragmentSignature(): Maybe<FragmentSignature>;
+    /**
+     * Returns the function used to look up fragment signatures by name.
+     * @returns A function that maps fragment names to fragment signatures.
+     * @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(
+     *   `
+     *     {
+     *       ...GreetingFields
+     *     }
+     *
+     *     fragment GreetingFields on Query {
+     *       greeting
+     *     }
+     *   `,
+     *   { experimentalFragmentArguments: true },
+     * );
+     * const typeInfo = new TypeInfo(schema);
+     * const context = new ValidationContext(schema, document, typeInfo, () => {});
+     * let fragmentName;
+     *
+     * visit(
+     *   document,
+     *   visitWithTypeInfo(typeInfo, {
+     *     Document: () => {
+     *       const getFragmentSignature = context.getFragmentSignatureByName();
+     *       fragmentName =
+     *         getFragmentSignature('GreetingFields')?.definition.name.value;
+     *     },
+     *   }),
+     * );
+     *
+     * fragmentName; // => 'GreetingFields'
+     * ```
+     */
     getFragmentSignatureByName(): (fragmentName: string) => Maybe<FragmentSignature>;
+    /**
+     * 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(): Maybe<GraphQLEnumValue>;
 }
+/** A function that creates an AST visitor for validating a GraphQL document. */
 export type ValidationRule = (context: ValidationContext) => ASTVisitor;
 export {};

package/validation/ValidationContext.js

@@ -1,14 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ValidationContext = exports.SDLValidationContext = exports.ASTValidationContext = void 0;
-const kinds_js_1 = require("../language/kinds.js");
-const visitor_js_1 = require("../language/visitor.js");
-const TypeInfo_js_1 = require("../utilities/TypeInfo.js");
-/**
- * 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.
- */
+const kinds_ts_1 = require("../language/kinds.js");
+const visitor_ts_1 = require("../language/visitor.js");
+const TypeInfo_ts_1 = require("../utilities/TypeInfo.js");
 class ASTValidationContext {
     constructor(ast, onError) {
         this._ast = ast;
@@ -34,7 +29,7 @@ class ASTValidationContext {
         else {
             fragments = Object.create(null);
             for (const defNode of this.getDocument().definitions) {
-                if (defNode.kind === kinds_js_1.Kind.FRAGMENT_DEFINITION) {
+                if (defNode.kind === kinds_ts_1.Kind.FRAGMENT_DEFINITION) {
                     fragments[defNode.name.value] = defNode;
                 }
             }
@@ -50,7 +45,7 @@ class ASTValidationContext {
             let set;
             while ((set = setsToVisit.pop())) {
                 for (const selection of set.selections) {
-                    if (selection.kind === kinds_js_1.Kind.FRAGMENT_SPREAD) {
+                    if (selection.kind === kinds_ts_1.Kind.FRAGMENT_SPREAD) {
                         spreads.push(selection);
                     }
                     else if (selection.selectionSet) {
@@ -126,9 +121,9 @@ class ValidationContext extends ASTValidationContext {
         let usages = this._variableUsages.get(node);
         if (!usages) {
             const newUsages = [];
-            const typeInfo = new TypeInfo_js_1.TypeInfo(this._schema, undefined, this._typeInfo.getFragmentSignatureByName());
-            const fragmentDefinition = node.kind === kinds_js_1.Kind.FRAGMENT_DEFINITION ? node : undefined;
-            (0, visitor_js_1.visit)(node, (0, TypeInfo_js_1.visitWithTypeInfo)(typeInfo, {
+            const typeInfo = new TypeInfo_ts_1.TypeInfo(this._schema, undefined, this._typeInfo.getFragmentSignatureByName());
+            const fragmentDefinition = node.kind === kinds_ts_1.Kind.FRAGMENT_DEFINITION ? node : undefined;
+            (0, visitor_ts_1.visit)(node, (0, TypeInfo_ts_1.visitWithTypeInfo)(typeInfo, {
                 VariableDefinition: () => false,
                 Variable(variable) {
                     let fragmentVariableDefinition;
@@ -140,7 +135,7 @@ class ValidationContext extends ASTValidationContext {
                             node: variable,
                             type: typeInfo.getInputType(),
                             parentType: typeInfo.getParentInputType(),
-                            defaultValue: undefined, // fragment variables have a variable default but no location default, which is what this default value represents
+                            defaultValue: undefined,
                             fragmentVariableDefinition,
                         });
                     }
@@ -180,8 +175,6 @@ class ValidationContext extends ASTValidationContext {
     getInputType() {
         return this._typeInfo.getInputType();
     }
-    // Note: continues to expose the closest enclosing valid input type if
-    // traversal descends into syntax with no corresponding GraphQL input type.
     getParentInputType() {
         return this._typeInfo.getParentInputType();
     }