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

package/type/schema.d.ts

@@ -1,18 +1,53 @@
-import type { Maybe } from '../jsutils/Maybe.js';
-import type { ObjMap } from '../jsutils/ObjMap.js';
-import type { GraphQLError } from '../error/GraphQLError.js';
-import type { SchemaDefinitionNode, SchemaExtensionNode } from '../language/ast.js';
-import { OperationTypeNode } from '../language/ast.js';
-import type { GraphQLAbstractType, GraphQLCompositeType, GraphQLField, GraphQLInterfaceType, GraphQLNamedType, GraphQLObjectType } from './definition.js';
-import type { GraphQLDirective } from './directives.js';
+/** @category Schema */
+import type { Maybe } from "../jsutils/Maybe.js";
+import type { ObjMap } from "../jsutils/ObjMap.js";
+import type { GraphQLError } from "../error/GraphQLError.js";
+import type { SchemaDefinitionNode, SchemaExtensionNode } from "../language/ast.js";
+import { OperationTypeNode } from "../language/ast.js";
+import type { GraphQLAbstractType, GraphQLCompositeType, GraphQLField, GraphQLInterfaceType, GraphQLNamedType, GraphQLObjectType } from "./definition.js";
+import type { GraphQLDirective } from "./directives.js";
 /**
  * Test if the given value is a GraphQL schema.
+ * @param schema - Value to inspect.
+ * @returns True when the value is a GraphQLSchema.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql/utilities';
+ * import { GraphQLString, isSchema } from 'graphql/type';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ *
+ * isSchema(schema); // => true
+ * isSchema(GraphQLString); // => false
+ * ```
  */
 export declare function isSchema(schema: unknown): schema is GraphQLSchema;
+/**
+ * Returns the value as a GraphQLSchema, or throws if it is not a schema.
+ * @param schema - GraphQL schema to use.
+ * @returns The value typed as a GraphQLSchema.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql/utilities';
+ * import { assertSchema, GraphQLString } from 'graphql/type';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ *
+ * assertSchema(schema); // => schema
+ * assertSchema(GraphQLString); // throws an error
+ * ```
+ */
 export declare function assertSchema(schema: unknown): GraphQLSchema;
 /**
  * Custom extensions
- *
  * @remarks
  * Use a unique identifier name for your extension, for example the name of
  * your library or project. Do not use a shortened identifier as this increases
@@ -22,83 +57,100 @@ export declare function assertSchema(schema: unknown): GraphQLSchema;
 export interface GraphQLSchemaExtensions {
     [attributeName: string | symbol]: unknown;
 }
-declare const schemaSymbol: unique symbol;
 /**
  * Schema Definition
  *
  * A Schema is created by supplying the root types of each type of operation,
  * query and mutation (optional). A schema definition is then supplied to the
  * validator and executor.
+ * @example
+ * ```ts
+ * const MyAppQueryRootType = new GraphQLObjectType({
+ *   name: 'Query',
+ *   fields: {
+ *     greeting: { type: GraphQLString },
+ *   },
+ * });
  *
- * Example:
+ * const MyAppMutationRootType = new GraphQLObjectType({
+ *   name: 'Mutation',
+ *   fields: {
+ *     setGreeting: { type: GraphQLString },
+ *   },
+ * });
  *
- * ```ts
  * const MyAppSchema = new GraphQLSchema({
  *   query: MyAppQueryRootType,
  *   mutation: MyAppMutationRootType,
- * })
+ * });
  * ```
- *
- * Note: When the schema is constructed, by default only the types that are
- * reachable by traversing the root types are included, other types must be
- * explicitly referenced.
- *
- * Example:
+ * @example
+ * When the schema is constructed, by default only the types that are reachable
+ * by traversing the root types are included, other types must be explicitly
+ * referenced.
  *
  * ```ts
  * const characterInterface = new GraphQLInterfaceType({
  *   name: 'Character',
- *   ...
+ *   fields: {
+ *     name: { type: GraphQLString },
+ *   },
  * });
  *
  * const humanType = new GraphQLObjectType({
  *   name: 'Human',
  *   interfaces: [characterInterface],
- *   ...
+ *   fields: {
+ *     name: { type: GraphQLString },
+ *   },
  * });
  *
  * const droidType = new GraphQLObjectType({
  *   name: 'Droid',
  *   interfaces: [characterInterface],
- *   ...
+ *   fields: {
+ *     name: { type: GraphQLString },
+ *   },
  * });
  *
  * const schema = new GraphQLSchema({
  *   query: new GraphQLObjectType({
  *     name: 'Query',
  *     fields: {
- *       hero: { type: characterInterface, ... },
- *     }
+ *       hero: { type: characterInterface },
+ *     },
  *   }),
- *   ...
  *   // Since this schema references only the `Character` interface it's
  *   // necessary to explicitly list the types that implement it if
  *   // you want them to be included in the final schema.
  *   types: [humanType, droidType],
- * })
+ * });
  * ```
- *
- * Note: If an array of `directives` are provided to GraphQLSchema, that will be
- * the exact list of directives represented and allowed. If `directives` is not
+ * @example
+ * If an array of `directives` are provided to GraphQLSchema, that will be the
+ * exact list of directives represented and allowed. If `directives` is not
  * provided then a default set of the specified directives (e.g. `@include` and
- * `@skip`) will be used. If you wish to provide *additional* directives to these
- * specified directives, you must explicitly declare them. Example:
+ * `@skip`) will be used. If you wish to provide *additional* directives to
+ * these specified directives, you must explicitly declare them.
  *
  * ```ts
  * const MyAppSchema = new GraphQLSchema({
- *   ...
- *   directives: specifiedDirectives.concat([ myCustomDirective ]),
- * })
+ *   query: MyAppQueryRootType,
+ *   directives: specifiedDirectives.concat([myCustomDirective]),
+ * });
  * ```
  */
 export declare class GraphQLSchema {
-    readonly __kind: typeof schemaSymbol;
+    /** Human-readable description for this schema element, if provided. */
     description: Maybe<string>;
+    /** Extension fields to include in the formatted result. */
     extensions: Readonly<GraphQLSchemaExtensions>;
+    /** AST node from which this schema element was built, if available. */
     astNode: Maybe<SchemaDefinitionNode>;
+    /** AST extension nodes applied to this schema element. */
     extensionASTNodes: ReadonlyArray<SchemaExtensionNode>;
+    /** Whether this schema instance skips validation checks. */
     assumeValid: boolean;
-    __validationErrors: Maybe<ReadonlyArray<GraphQLError>>;
     private _queryType;
     private _mutationType;
     private _subscriptionType;
@@ -106,21 +158,392 @@ export declare class GraphQLSchema {
     private _typeMap;
     private _subTypeMap;
     private _implementationsMap;
+    /**
+     * Creates a GraphQLSchema instance.
+     * @param config - Configuration describing this object.
+     * @example
+     * ```ts
+     * // Create a schema with the required query root.
+     * import {
+     *   GraphQLObjectType,
+     *   GraphQLSchema,
+     *   GraphQLString,
+     * } from 'graphql/type';
+     *
+     * const Query = new GraphQLObjectType({
+     *   name: 'Query',
+     *   fields: {
+     *     greeting: {
+     *       type: GraphQLString,
+     *       resolve: () => 'Hello',
+     *     },
+     *   },
+     * });
+     *
+     * const schema = new GraphQLSchema({
+     *   description: 'The application schema.',
+     *   query: Query,
+     * });
+     *
+     * schema.getQueryType(); // => Query
+     * schema.description; // => 'The application schema.'
+     * ```
+     * @example
+     * ```ts
+     * // This variant configures every schema option, including directives and extensions.
+     * import { DirectiveLocation, parse } from 'graphql/language';
+     * import {
+     *   GraphQLBoolean,
+     *   GraphQLDirective,
+     *   GraphQLObjectType,
+     *   GraphQLSchema,
+     *   GraphQLString,
+     * } from 'graphql/type';
+     *
+     * const Query = new GraphQLObjectType({
+     *   name: 'Query',
+     *   fields: { greeting: { type: GraphQLString } },
+     * });
+     * const Mutation = new GraphQLObjectType({
+     *   name: 'Mutation',
+     *   fields: { setGreeting: { type: GraphQLString } },
+     * });
+     * const Subscription = new GraphQLObjectType({
+     *   name: 'Subscription',
+     *   fields: { greetingChanged: { type: GraphQLString } },
+     * });
+     * const AuditEvent = new GraphQLObjectType({
+     *   name: 'AuditEvent',
+     *   fields: { message: { type: GraphQLString } },
+     * });
+     * const authDirective = new GraphQLDirective({
+     *   name: 'auth',
+     *   locations: [DirectiveLocation.FIELD_DEFINITION],
+     *   args: { required: { type: GraphQLBoolean } },
+     * });
+     * const schemaDocument = parse(`
+     *   schema {
+     *     query: Query
+     *     mutation: Mutation
+     *     subscription: Subscription
+     *   }
+     *
+     *   extend schema @auth
+     * `);
+     *
+     * const schema = new GraphQLSchema({
+     *   description: 'Operations exposed by the application.',
+     *   query: Query,
+     *   mutation: Mutation,
+     *   subscription: Subscription,
+     *   types: [AuditEvent],
+     *   directives: [authDirective],
+     *   extensions: { owner: 'platform' },
+     *   astNode: schemaDocument.definitions[0],
+     *   extensionASTNodes: [ schemaDocument.definitions[1] ],
+     *   assumeValid: true,
+     * });
+     *
+     * schema.getMutationType(); // => Mutation
+     * schema.getSubscriptionType(); // => Subscription
+     * schema.getType('AuditEvent'); // => AuditEvent
+     * schema.getDirective('auth'); // => authDirective
+     * schema.extensions; // => { owner: 'platform' }
+     * ```
+     */
     constructor(config: Readonly<GraphQLSchemaConfig>);
+    /**
+     * Returns the value used by `Object.prototype.toString`.
+     * @returns The built-in string tag for this object.
+     */
     get [Symbol.toStringTag](): string;
+    /**
+     * Returns the root object type for query operations.
+     * @returns The query root type, if this schema defines one.
+     * @example
+     * ```ts
+     * import { buildSchema } from 'graphql/utilities';
+     *
+     * const schema = buildSchema(`
+     *   type Query {
+     *     greeting: String
+     *   }
+     * `);
+     *
+     * schema.getQueryType()?.name; // => 'Query'
+     * ```
+     */
     getQueryType(): Maybe<GraphQLObjectType>;
+    /**
+     * Returns the root object type for mutation operations.
+     * @returns The mutation root type, if this schema defines one.
+     * @example
+     * ```ts
+     * import { buildSchema } from 'graphql/utilities';
+     *
+     * const schema = buildSchema(`
+     *   type Query {
+     *     greeting: String
+     *   }
+     *
+     *   type Mutation {
+     *     setGreeting(value: String!): String
+     *   }
+     * `);
+     *
+     * schema.getMutationType()?.name; // => 'Mutation'
+     * ```
+     */
     getMutationType(): Maybe<GraphQLObjectType>;
+    /**
+     * Returns the root object type for subscription operations.
+     * @returns The subscription root type, if this schema defines one.
+     * @example
+     * ```ts
+     * import { buildSchema } from 'graphql/utilities';
+     *
+     * const schema = buildSchema(`
+     *   type Query {
+     *     greeting: String
+     *   }
+     *
+     *   type Subscription {
+     *     greetings: String
+     *   }
+     * `);
+     *
+     * schema.getSubscriptionType()?.name; // => 'Subscription'
+     * ```
+     */
     getSubscriptionType(): Maybe<GraphQLObjectType>;
+    /**
+     * Returns the root object type for the requested operation kind.
+     * @param operation - Operation kind to resolve.
+     * @returns The root object type for the operation kind, if this schema defines one.
+     * @example
+     * ```ts
+     * import { OperationTypeNode } from 'graphql/language';
+     * import { buildSchema } from 'graphql/utilities';
+     *
+     * const schema = buildSchema(`
+     *   type Query {
+     *     greeting: String
+     *   }
+     *
+     *   type Mutation {
+     *     setGreeting(value: String!): String
+     *   }
+     * `);
+     *
+     * schema.getRootType(OperationTypeNode.QUERY)?.name; // => 'Query'
+     * schema.getRootType(OperationTypeNode.MUTATION)?.name; // => 'Mutation'
+     * schema.getRootType(OperationTypeNode.SUBSCRIPTION); // => undefined
+     * ```
+     */
     getRootType(operation: OperationTypeNode): Maybe<GraphQLObjectType>;
+    /**
+     * Returns all named types known to this schema.
+     * @returns A map of schema types keyed by type name.
+     * @example
+     * ```ts
+     * import { buildSchema } from 'graphql/utilities';
+     *
+     * const schema = buildSchema(`
+     *   type User {
+     *     name: String
+     *   }
+     *
+     *   type Query {
+     *     viewer: User
+     *   }
+     * `);
+     *
+     * const typeMap = schema.getTypeMap();
+     *
+     * typeMap.User.name; // => 'User'
+     * typeMap.Query.name; // => 'Query'
+     * typeMap.String.name; // => 'String'
+     * ```
+     */
     getTypeMap(): TypeMap;
+    /**
+     * Returns the named type with the provided name.
+     * @param name - The GraphQL name to look up.
+     * @returns The named schema type, if one exists.
+     * @example
+     * ```ts
+     * import { buildSchema } from 'graphql/utilities';
+     *
+     * const schema = buildSchema(`
+     *   type User {
+     *     name: String
+     *   }
+     *
+     *   type Query {
+     *     viewer: User
+     *   }
+     * `);
+     *
+     * schema.getType('User')?.toString(); // => 'User'
+     * schema.getType('Missing'); // => undefined
+     * ```
+     */
     getType(name: string): GraphQLNamedType | undefined;
+    /**
+     * Returns object types that may be returned for an abstract type.
+     * @param abstractType - Interface or union type to inspect.
+     * @returns Object types that may satisfy the abstract type.
+     * @example
+     * ```ts
+     * import { buildSchema } from 'graphql/utilities';
+     * import { assertInterfaceType, assertUnionType } from 'graphql/type';
+     *
+     * const schema = buildSchema(`
+     *   interface Node {
+     *     id: ID!
+     *   }
+     *
+     *   type User implements Node {
+     *     id: ID!
+     *   }
+     *
+     *   type Organization implements Node {
+     *     id: ID!
+     *   }
+     *
+     *   union SearchResult = User | Organization
+     *
+     *   type Query {
+     *     node: Node
+     *     search: [SearchResult]
+     *   }
+     * `);
+     *
+     * const Node = assertInterfaceType(schema.getType('Node'));
+     * const SearchResult = assertUnionType(schema.getType('SearchResult'));
+     *
+     * schema.getPossibleTypes(Node).map((type) => type.name); // => ['User', 'Organization']
+     * schema.getPossibleTypes(SearchResult).map((type) => type.name); // => ['User', 'Organization']
+     * ```
+     */
     getPossibleTypes(abstractType: GraphQLAbstractType): ReadonlyArray<GraphQLObjectType>;
+    /**
+     * Returns objects and interfaces that implement an interface type.
+     * @param interfaceType - Interface type to inspect.
+     * @returns Object and interface implementations of the interface.
+     * @example
+     * ```ts
+     * import { buildSchema } from 'graphql/utilities';
+     * import { assertInterfaceType } from 'graphql/type';
+     *
+     * const schema = buildSchema(`
+     *   interface Resource {
+     *     url: String!
+     *   }
+     *
+     *   interface Image implements Resource {
+     *     url: String!
+     *     width: Int
+     *   }
+     *
+     *   type Photo implements Resource & Image {
+     *     url: String!
+     *     width: Int
+     *   }
+     *
+     *   type Query {
+     *     resource: Resource
+     *   }
+     * `);
+     *
+     * const Resource = assertInterfaceType(schema.getType('Resource'));
+     * const implementations = schema.getImplementations(Resource);
+     *
+     * implementations.interfaces.map((type) => type.name); // => ['Image']
+     * implementations.objects.map((type) => type.name); // => ['Photo']
+     * ```
+     */
     getImplementations(interfaceType: GraphQLInterfaceType): {
         objects: ReadonlyArray<GraphQLObjectType>;
         interfaces: ReadonlyArray<GraphQLInterfaceType>;
     };
+    /**
+     * Returns whether one type is a possible runtime subtype of an abstract type.
+     * @param abstractType - Interface or union type to inspect.
+     * @param maybeSubType - Object or interface type to test as a possible subtype.
+     * @returns True when the subtype may satisfy the abstract type.
+     * @example
+     * ```ts
+     * import { buildSchema } from 'graphql/utilities';
+     * import { assertInterfaceType, assertObjectType } from 'graphql/type';
+     *
+     * const schema = buildSchema(`
+     *   interface Node {
+     *     id: ID!
+     *   }
+     *
+     *   type User implements Node {
+     *     id: ID!
+     *   }
+     *
+     *   type Review {
+     *     body: String
+     *   }
+     *
+     *   type Query {
+     *     node: Node
+     *     review: Review
+     *   }
+     * `);
+     *
+     * const Node = assertInterfaceType(schema.getType('Node'));
+     * const User = assertObjectType(schema.getType('User'));
+     * const Review = assertObjectType(schema.getType('Review'));
+     *
+     * schema.isSubType(Node, User); // => true
+     * schema.isSubType(Node, Review); // => false
+     * ```
+     */
     isSubType(abstractType: GraphQLAbstractType, maybeSubType: GraphQLObjectType | GraphQLInterfaceType): boolean;
+    /**
+     * Returns directives available in this schema.
+     * @returns Directives available in this schema.
+     * @example
+     * ```ts
+     * import { buildSchema } from 'graphql/utilities';
+     *
+     * const schema = buildSchema(`
+     *   directive @upper on FIELD_DEFINITION
+     *
+     *   type Query {
+     *     greeting: String @upper
+     *   }
+     * `);
+     *
+     * schema.getDirectives().map((directive) => directive.name); // => ['include', 'skip', 'deprecated', 'specifiedBy', 'oneOf', 'upper']
+     * ```
+     */
     getDirectives(): ReadonlyArray<GraphQLDirective>;
+    /**
+     * Returns the current directive definition.
+     * @param name - The GraphQL name to look up.
+     * @returns The current directive definition, if known.
+     * @example
+     * ```ts
+     * import { buildSchema } from 'graphql/utilities';
+     *
+     * const schema = buildSchema(`
+     *   directive @upper on FIELD_DEFINITION
+     *
+     *   type Query {
+     *     greeting: String @upper
+     *   }
+     * `);
+     *
+     * schema.getDirective('upper')?.name; // => 'upper'
+     * schema.getDirective('missing'); // => undefined
+     * ```
+     */
     getDirective(name: string): Maybe<GraphQLDirective>;
     /**
      * This method looks up the field on the given type definition.
@@ -132,11 +555,54 @@ export declare class GraphQLSchema {
      *
      * `__schema` and `__type` could get automatically added to the query type,
      * but that would require mutating type definitions, which would cause issues.
+     * @param parentType - Composite type to look up the field on.
+     * @param fieldName - Field name to look up.
+     * @returns The field definition, including supported introspection fields.
+     * @example
+     * ```ts
+     * import { buildSchema } from 'graphql/utilities';
+     *
+     * const schema = buildSchema(`
+     *   type Query {
+     *     greeting: String
+     *   }
+     * `);
+     * const queryType = schema.getQueryType();
+     *
+     * schema.getField(queryType, 'greeting')?.name; // => 'greeting'
+     * schema.getField(queryType, '__typename')?.name; // => '__typename'
+     * schema.getField(queryType, 'missing'); // => undefined
+     * ```
      */
     getField(parentType: GraphQLCompositeType, fieldName: string): GraphQLField<unknown, unknown> | undefined;
+    /**
+     * Returns a normalized configuration object for this object.
+     *
+     * The returned config preserves the original `assumeValid` flag so the schema
+     * can be recreated with the same validation behavior.
+     * @returns A configuration object that can be used to recreate this object.
+     * @example
+     * ```ts
+     * import { buildSchema } from 'graphql/utilities';
+     * import { GraphQLSchema } from 'graphql/type';
+     *
+     * const schema = buildSchema(`
+     *   type Query {
+     *     greeting: String
+     *   }
+     * `);
+     *
+     * const config = schema.toConfig();
+     * const schemaCopy = new GraphQLSchema(config);
+     *
+     * config.query?.name; // => 'Query'
+     * schemaCopy.getQueryType()?.name; // => 'Query'
+     * ```
+     */
     toConfig(): GraphQLSchemaNormalizedConfig;
 }
 type TypeMap = ObjMap<GraphQLNamedType>;
+/** @internal */
 export interface GraphQLSchemaValidationOptions {
     /**
      * When building a schema from a GraphQL service's introspection result, it
@@ -144,23 +610,33 @@ export interface GraphQLSchemaValidationOptions {
      * produced schema is valid.
      *
      * Default: false
+     *
+     * @internal
      */
     assumeValid?: boolean | undefined;
 }
+/** Configuration used to construct a GraphQLSchema. */
 export interface GraphQLSchemaConfig extends GraphQLSchemaValidationOptions {
+    /** Human-readable description for this schema element, if provided. */
     description?: Maybe<string>;
+    /** Root object type for query operations. */
     query?: Maybe<GraphQLObjectType>;
+    /** Root object type for mutation operations. */
     mutation?: Maybe<GraphQLObjectType>;
+    /** Root object type for subscription operations. */
     subscription?: Maybe<GraphQLObjectType>;
+    /** Object types that belong to this union type. */
     types?: Maybe<ReadonlyArray<GraphQLNamedType>>;
+    /** Directives available in this schema or applied to this AST node. */
     directives?: Maybe<ReadonlyArray<GraphQLDirective>>;
+    /** Extension fields to include in the formatted result. */
     extensions?: Maybe<Readonly<GraphQLSchemaExtensions>>;
+    /** AST node from which this schema element was built, if available. */
     astNode?: Maybe<SchemaDefinitionNode>;
+    /** AST extension nodes applied to this schema element. */
     extensionASTNodes?: Maybe<ReadonlyArray<SchemaExtensionNode>>;
 }
-/**
- * @internal
- */
+/** @internal */
 export interface GraphQLSchemaNormalizedConfig extends GraphQLSchemaConfig {
     description: Maybe<string>;
     types: ReadonlyArray<GraphQLNamedType>;