graphql

graphql

Version 16.8.1
Published 2 months ago
1.34 MB
No dependencies
MIT license

Install

npm i graphql

yarn add graphql

pnpm add graphql

Overview

GraphQL.js provides a reference implementation for the GraphQL specification but is also a useful utility for operating on GraphQL files and building sophisticated tools.

This primary module exports a general purpose function for fulfilling all steps of the GraphQL specification in a single operation, but also includes utilities for every part of the GraphQL specification:

- Parsing the GraphQL language. - Building a GraphQL type schema. - Validating a GraphQL request against a type schema. - Executing a GraphQL request against a type schema.

This also includes utility functions for operating on GraphQL types and GraphQL documents to facilitate building tools.

You may also import from each sub-directory directly. For example, the following two import statements are equivalent:

import { parse } from 'graphql';
import { parse } from 'graphql/language';

Index

Variables

variable BREAK

const BREAK: {};

variable DEFAULT_DEPRECATION_REASON

const DEFAULT_DEPRECATION_REASON: string;

Constant string used for default reason for a deprecation.

variable defaultFieldResolver

const defaultFieldResolver: GraphQLFieldResolver<unknown, unknown, any, unknown>;

If a resolve function is not given, then a default resolve behavior is used which takes the property of the source object of the same name as the field and returns it as the result, or if it's a function, returns the result of calling that function while passing along args and context value.

variable defaultTypeResolver

const defaultTypeResolver: GraphQLTypeResolver<unknown, unknown>;

If a resolveType function is not given, then a default resolve behavior is used which attempts two strategies:
First, See if the provided value has a __typename field defined, if so, use that value as name of the resolved type.
Otherwise, test each possible type for the abstract type by calling isTypeOf for the object being coerced, returning the first type that matches.

variable GRAPHQL_MAX_INT

const GRAPHQL_MAX_INT: number;

Maximum possible Int value as per GraphQL Spec (32-bit signed integer). n.b. This differs from JavaScript's numbers that are IEEE 754 doubles safe up-to 2^53 - 1

variable GRAPHQL_MIN_INT

const GRAPHQL_MIN_INT: number;

Minimum possible Int value as per GraphQL Spec (32-bit signed integer). n.b. This differs from JavaScript's numbers that are IEEE 754 doubles safe starting at -(2^53 - 1)

variable GraphQLBoolean

const GraphQLBoolean: GraphQLScalarType<boolean, boolean>;

variable GraphQLDeprecatedDirective

const GraphQLDeprecatedDirective: GraphQLDirective;

Used to declare element of a GraphQL schema as deprecated.

variable GraphQLFloat

const GraphQLFloat: GraphQLScalarType<number, number>;

variable GraphQLID

const GraphQLID: GraphQLScalarType<string, string>;

variable GraphQLIncludeDirective

const GraphQLIncludeDirective: GraphQLDirective;

Used to conditionally include fields or fragments.

variable GraphQLInt

const GraphQLInt: GraphQLScalarType<number, number>;

variable GraphQLSkipDirective

const GraphQLSkipDirective: GraphQLDirective;

Used to conditionally skip (exclude) fields or fragments.

variable GraphQLSpecifiedByDirective

const GraphQLSpecifiedByDirective: GraphQLDirective;

Used to provide a URL for specifying the behavior of custom scalar definitions.

variable GraphQLString

const GraphQLString: GraphQLScalarType<string, string>;

variable introspectionTypes

const introspectionTypes: readonly GraphQLNamedType[];

variable SchemaMetaFieldDef

const SchemaMetaFieldDef: GraphQLField<unknown, unknown, any>;

Note that these are GraphQLField and not GraphQLFieldConfig, so the format for args is different.

variable specifiedDirectives

const specifiedDirectives: readonly GraphQLDirective[];

The full list of specified directives.

variable specifiedRules

const specifiedRules: readonly ValidationRule[];

This set includes all validation rules defined by the GraphQL spec.
The order of the rules in this list has been adjusted to lead to the most clear output when encountering multiple validation errors.

variable specifiedScalarTypes

const specifiedScalarTypes: readonly GraphQLScalarType<unknown, unknown>[];

variable TypeMetaFieldDef

const TypeMetaFieldDef: GraphQLField<unknown, unknown, any>;

variable TypeNameMetaFieldDef

const TypeNameMetaFieldDef: GraphQLField<unknown, unknown, any>;

variable version

const version: string;

A string containing the version of the GraphQL.js library

variable versionInfo

const versionInfo: Readonly<{
    major: number;
    minor: number;
    patch: number;
    preReleaseTag: string | null;
}>;

An object containing the components of the GraphQL.js version string

Functions

function assertAbstractType

assertAbstractType: (type: unknown) => GraphQLAbstractType;

function assertCompositeType

assertCompositeType: (type: unknown) => GraphQLCompositeType;

function assertDirective

assertDirective: (directive: unknown) => GraphQLDirective;

function assertEnumType

assertEnumType: (type: unknown) => GraphQLEnumType;

function assertInputObjectType

assertInputObjectType: (type: unknown) => GraphQLInputObjectType;

function assertInputType

assertInputType: (type: unknown) => GraphQLInputType;

function assertInterfaceType

assertInterfaceType: (type: unknown) => GraphQLInterfaceType;

function assertLeafType

assertLeafType: (type: unknown) => GraphQLLeafType;

function assertListType

assertListType: (type: unknown) => GraphQLList<GraphQLType>;

function assertName

assertName: (name: string) => string;

Upholds the spec rules about naming.

function assertNamedType

assertNamedType: (type: unknown) => GraphQLNamedType;

function assertNonNullType

assertNonNullType: (type: unknown) => GraphQLNonNull<GraphQLType>;

function assertNullableType

assertNullableType: (type: unknown) => GraphQLNullableType;

function assertObjectType

assertObjectType: (type: unknown) => GraphQLObjectType;

function assertOutputType

assertOutputType: (type: unknown) => GraphQLOutputType;

function assertScalarType

assertScalarType: (type: unknown) => GraphQLScalarType;

function assertSchema

assertSchema: (schema: unknown) => GraphQLSchema;

function assertType

assertType: (type: unknown) => GraphQLType;

function assertUnionType

assertUnionType: (type: unknown) => GraphQLUnionType;

function assertValidName

assertValidName: (name: string) => string;

Upholds the spec rules about naming.
Deprecated
Please use assertName instead. Will be removed in v17

function assertValidSchema

assertValidSchema: (schema: GraphQLSchema) => void;

Utility function which asserts a schema is valid by throwing an error if it is invalid.

function assertWrappingType

assertWrappingType: (type: unknown) => GraphQLWrappingType;

function astFromValue

astFromValue: (value: unknown, type: GraphQLInputType) => Maybe<ValueNode>;

Produces a GraphQL Value AST given a JavaScript object. Function will match JavaScript/JSON values to GraphQL AST schema format by using suggested GraphQLInputType. For example:
astFromValue("value", GraphQLString)
A GraphQL type must be provided, which will be used to interpret different JavaScript values.
| JSON Value | GraphQL Value | | ------------- | -------------------- | | Object | Input Object | | Array | List | | Boolean | Boolean | | String | String / Enum Value | | Number | Int / Float | | Unknown | Enum Value | | null | NullValue |

function buildASTSchema

buildASTSchema: (
    documentAST: DocumentNode,
    options?: BuildSchemaOptions
) => GraphQLSchema;

This takes the ast of a schema document produced by the parse function in src/language/parser.js.
If no schema definition is provided, then it will look for types named Query, Mutation and Subscription.
Given that AST it constructs a GraphQLSchema. The resulting schema has no resolve methods, so execution will use default resolvers.

function buildClientSchema

buildClientSchema: (
    introspection: IntrospectionQuery,
    options?: GraphQLSchemaValidationOptions
) => GraphQLSchema;

Build a GraphQLSchema for use by client tools.
Given the result of a client running the introspection query, creates and returns a GraphQLSchema instance which can be then used with all graphql-js tools, but cannot be used to execute a query, as introspection does not represent the "resolver", "parse" or "serialize" functions or any other server-internal mechanisms.
This function expects a complete introspection result. Don't forget to check the "errors" field of a server response before calling this function.

function buildSchema

buildSchema: (
    source: string | Source,
    options?: BuildSchemaOptions & ParseOptions
) => GraphQLSchema;

A helper function to build a GraphQLSchema directly from a source document.

function coerceInputValue

coerceInputValue: (
    inputValue: unknown,
    type: GraphQLInputType,
    onError?: OnErrorCB
) => unknown;

Coerces a JavaScript value given a GraphQL Input Type.

function concatAST

concatAST: (documents: ReadonlyArray<DocumentNode>) => DocumentNode;

Provided a collection of ASTs, presumably each from different files, concatenate the ASTs together into batched AST, useful for validating many GraphQL source files which together represent one conceptual application.

function createSourceEventStream

createSourceEventStream: {
    (args: ExecutionArgs): Promise<AsyncIterable<unknown> | ExecutionResult>;
    (
        schema: GraphQLSchema,
        document: DocumentNode,
        rootValue?: unknown,
        contextValue?: unknown,
        variableValues?: { readonly [variable: string]: unknown },
        operationName?: string,
        subscribeFieldResolver?: GraphQLFieldResolver<any, any, any, unknown>
    ): Promise<
        ExecutionResult<ObjMap<unknown>, ObjMap<unknown>> | AsyncIterable<unknown>
    >;
};

Implements the "CreateSourceEventStream" algorithm described in the GraphQL specification, resolving the subscription source event stream.
Returns a Promise which resolves to either an AsyncIterable (if successful) or an ExecutionResult (error). The promise will be rejected if the schema or other arguments to this function are invalid, or if the resolved event stream is not an async iterable.
If the client-provided arguments to this function do not result in a compliant subscription, a GraphQL Response (ExecutionResult) with descriptive errors and no data will be returned.
If the the source stream could not be created due to faulty subscription resolver logic or underlying systems, the promise will resolve to a single ExecutionResult containing errors and no data.
If the operation succeeded, the promise resolves to the AsyncIterable for the event stream returned by the resolver.
A Source Event Stream represents a sequence of events, each of which triggers a GraphQL execution for that event.
This may be useful when hosting the stateful subscription service in a different process or machine than the stateless GraphQL execution engine, or otherwise separating these two steps. For more on this, see the "Supporting Subscriptions at Scale" information in the GraphQL specification.
Deprecated
will be removed in next major version in favor of named arguments

function doTypesOverlap

doTypesOverlap: (
    schema: GraphQLSchema,
    typeA: GraphQLCompositeType,
    typeB: GraphQLCompositeType
) => boolean;

Provided two composite types, determine if they "overlap". Two composite types overlap when the Sets of possible concrete types for each intersect.
This is often used to determine if a fragment of a given type could possibly be visited in a context of another type.
This function is commutative.

function ExecutableDefinitionsRule

ExecutableDefinitionsRule: (context: ASTValidationContext) => ASTVisitor;

Executable definitions
A GraphQL document is only valid for execution if all definitions are either operation or fragment definitions.
See https://spec.graphql.org/draft/#sec-Executable-Definitions

function execute

execute: (args: ExecutionArgs) => PromiseOrValue<ExecutionResult>;

Implements the "Executing requests" section of the GraphQL specification.
Returns either a synchronous ExecutionResult (if all encountered resolvers are synchronous), or a Promise of an ExecutionResult that will eventually be resolved and never rejected.
If the arguments to this function do not result in a legal execution context, a GraphQLError will be thrown immediately explaining the invalid input.

function executeSync

executeSync: (args: ExecutionArgs) => ExecutionResult;

Also implements the "Executing requests" section of the GraphQL specification. However, it guarantees to complete synchronously (or throw an error) assuming that all field resolvers are also synchronous.

function extendSchema

extendSchema: (
    schema: GraphQLSchema,
    documentAST: DocumentNode,
    options?: Options
) => GraphQLSchema;

Produces a new schema given an existing schema and a document which may contain GraphQL type extensions and definitions. The original schema will remain unaltered.
Because a schema represents a graph of references, a schema cannot be extended without effectively making an entire copy. We do not know until it's too late if subgraphs remain unchanged.
This algorithm copies the provided schema, applying extensions while producing the copy. The original schema remains unaltered.

function FieldsOnCorrectTypeRule

FieldsOnCorrectTypeRule: (context: ValidationContext) => ASTVisitor;

Fields on correct type
A GraphQL document is only valid if all fields selected are defined by the parent type, or are an allowed meta field such as __typename.
See https://spec.graphql.org/draft/#sec-Field-Selections

function findBreakingChanges

findBreakingChanges: (
    oldSchema: GraphQLSchema,
    newSchema: GraphQLSchema
) => Array<BreakingChange>;

Given two schemas, returns an Array containing descriptions of all the types of breaking changes covered by the other functions down below.

function findDangerousChanges

findDangerousChanges: (
    oldSchema: GraphQLSchema,
    newSchema: GraphQLSchema
) => Array<DangerousChange>;

Given two schemas, returns an Array containing descriptions of all the types of potentially dangerous changes covered by the other functions down below.

function formatError

formatError: (error: GraphQLError) => GraphQLFormattedError;

Given a GraphQLError, format it according to the rules described by the Response Format, Errors section of the GraphQL Specification.
Deprecated
Please use error.toJSON instead. Will be removed in v17

function FragmentsOnCompositeTypesRule

FragmentsOnCompositeTypesRule: (context: ValidationContext) => ASTVisitor;

Fragments on composite type
Fragments use a type condition to determine if they apply, since fragments can only be spread into a composite type (object, interface, or union), the type condition must also be a composite type.
See https://spec.graphql.org/draft/#sec-Fragments-On-Composite-Types

function getArgumentValues

getArgumentValues: (
    def: GraphQLField<unknown, unknown> | GraphQLDirective,
    node: FieldNode | DirectiveNode,
    variableValues?: Maybe<ObjMap<unknown>>
) => { [argument: string]: unknown };

Prepares an object map of argument values given a list of argument definitions and list of argument AST nodes.
Note: The returned value is a plain Object with a prototype, since it is exposed to user code. Care should be taken to not pull values from the Object prototype.

function getDirectiveValues

getDirectiveValues: (
    directiveDef: GraphQLDirective,
    node: { readonly directives?: ReadonlyArray<DirectiveNode> },
    variableValues?: Maybe<ObjMap<unknown>>
) => { [argument: string]: unknown };

Prepares an object map of argument values given a directive definition and a AST node which may contain directives. Optionally also accepts a map of variable values.
If the directive does not exist on the node, returns undefined.
Note: The returned value is a plain Object with a prototype, since it is exposed to user code. Care should be taken to not pull values from the Object prototype.

function getEnterLeaveForKind

getEnterLeaveForKind: (
    visitor: ASTVisitor,
    kind: Kind
) => EnterLeaveVisitor<ASTNode>;

Given a visitor instance and a node kind, return EnterLeaveVisitor for that kind.

function getIntrospectionQuery

getIntrospectionQuery: (options?: IntrospectionOptions) => string;

Produce the GraphQL query recommended for a full schema introspection. Accepts optional IntrospectionOptions.

function getLocation

getLocation: (source: Source, position: number) => SourceLocation;

Takes a Source and a UTF-8 character offset, and returns the corresponding line and column as a SourceLocation.

function getNamedType

getNamedType: {
    (type: undefined | null): void;
    (type: GraphQLInputType): GraphQLNamedInputType;
    (type: GraphQLOutputType): GraphQLNamedOutputType;
    (type: GraphQLType): GraphQLNamedType;
    (type: GraphQLType): GraphQLNamedType;
};

function getNullableType

getNullableType: {
    (type: undefined | null): void;
    <T extends GraphQLNullableType>(type: T | GraphQLNonNull<T>): T;
    (type: GraphQLType): GraphQLNullableType;
};

function getOperationAST

getOperationAST: (
    documentAST: DocumentNode,
    operationName?: Maybe<string>
) => Maybe<OperationDefinitionNode>;

Returns an operation AST given a document AST and optionally an operation name. If a name is not provided, an operation is only returned if only one is provided in the document.

function getOperationRootType

getOperationRootType: (
    schema: GraphQLSchema,
    operation: OperationDefinitionNode | OperationTypeDefinitionNode
) => GraphQLObjectType;

Extracts the root type of the operation from the schema.
Deprecated
Please use GraphQLSchema.getRootType instead. Will be removed in v17

function getVariableValues

getVariableValues: (
    schema: GraphQLSchema,
    varDefNodes: ReadonlyArray<VariableDefinitionNode>,
    inputs: { readonly [variable: string]: unknown },
    options?: { maxErrors?: number }
) => CoercedVariableValues;

Prepares an object map of variableValues of the correct type based on the provided variable definitions and arbitrary input. If the input cannot be parsed to match the variable definitions, a GraphQLError will be thrown.
Note: The returned value is a plain Object with a prototype, since it is exposed to user code. Care should be taken to not pull values from the Object prototype.

function getVisitFn

getVisitFn: (
    visitor: ASTVisitor,
    kind: Kind,
    isLeaving: boolean
) => ASTVisitFn<ASTNode> | undefined;

Given a visitor instance, if it is leaving or not, and a node kind, return the function the visitor runtime should call.
Deprecated
Please use getEnterLeaveForKind instead. Will be removed in v17

function graphql

graphql: (args: GraphQLArgs) => Promise<ExecutionResult>;

function graphqlSync

graphqlSync: (args: GraphQLArgs) => ExecutionResult;

The graphqlSync function also fulfills GraphQL operations by parsing, validating, and executing a GraphQL document along side a GraphQL schema. However, it guarantees to complete synchronously (or throw an error) assuming that all field resolvers are also synchronous.

function introspectionFromSchema

introspectionFromSchema: (
    schema: GraphQLSchema,
    options?: IntrospectionOptions
) => IntrospectionQuery;

Build an IntrospectionQuery from a GraphQLSchema
IntrospectionQuery is useful for utilities that care about type and field relationships, but do not need to traverse through those relationships.
This is the inverse of buildClientSchema. The primary use case is outside of the server context, for instance when doing schema comparisons.

function isAbstractType

isAbstractType: (type: unknown) => type is GraphQLAbstractType;

function isCompositeType

isCompositeType: (type: unknown) => type is GraphQLCompositeType;

function isConstValueNode

isConstValueNode: (node: ASTNode) => node is ConstValueNode;

function isDefinitionNode

isDefinitionNode: (node: ASTNode) => node is DefinitionNode;

function isDirective

isDirective: (directive: unknown) => directive is GraphQLDirective;

Test if the given value is a GraphQL directive.

function isEnumType

isEnumType: (type: unknown) => type is GraphQLEnumType;

function isEqualType

isEqualType: (typeA: GraphQLType, typeB: GraphQLType) => boolean;

Provided two types, return true if the types are equal (invariant).

function isExecutableDefinitionNode

isExecutableDefinitionNode: (node: ASTNode) => node is ExecutableDefinitionNode;

function isInputObjectType

isInputObjectType: (type: unknown) => type is GraphQLInputObjectType;

function isInputType

isInputType: (type: unknown) => type is GraphQLInputType;

function isInterfaceType

isInterfaceType: (type: unknown) => type is GraphQLInterfaceType;

function isIntrospectionType

isIntrospectionType: (type: GraphQLNamedType) => boolean;

function isLeafType

isLeafType: (type: unknown) => type is GraphQLLeafType;

function isListType

isListType: {
    (type: GraphQLInputType): type is GraphQLList<GraphQLInputType>;
    (type: GraphQLOutputType): type is GraphQLList<GraphQLOutputType>;
    (type: unknown): type is GraphQLList<GraphQLType>;
};

function isNamedType

isNamedType: (type: unknown) => type is GraphQLNamedType;

function isNonNullType

isNonNullType: {
    (type: GraphQLInputType): type is GraphQLNonNull<GraphQLInputType>;
    (type: GraphQLOutputType): type is GraphQLNonNull<GraphQLOutputType>;
    (type: unknown): type is GraphQLNonNull<GraphQLType>;
};

function isNullableType

isNullableType: (type: unknown) => type is GraphQLNullableType;

function isObjectType

isObjectType: (type: unknown) => type is GraphQLObjectType<any, any>;

function isOutputType

isOutputType: (type: unknown) => type is GraphQLOutputType;

function isRequiredArgument

isRequiredArgument: (arg: GraphQLArgument) => boolean;

function isRequiredInputField

isRequiredInputField: (field: GraphQLInputField) => boolean;

function isScalarType

isScalarType: (type: unknown) => type is GraphQLScalarType<unknown, unknown>;

There are predicates for each kind of GraphQL type.

function isSchema

isSchema: (schema: unknown) => schema is GraphQLSchema;

Test if the given value is a GraphQL schema.

function isSelectionNode

isSelectionNode: (node: ASTNode) => node is SelectionNode;

function isSpecifiedDirective

isSpecifiedDirective: (directive: GraphQLDirective) => boolean;

function isSpecifiedScalarType

isSpecifiedScalarType: (type: GraphQLNamedType) => boolean;

function isType

isType: (type: unknown) => type is GraphQLType;

function isTypeDefinitionNode

isTypeDefinitionNode: (node: ASTNode) => node is TypeDefinitionNode;

function isTypeExtensionNode

isTypeExtensionNode: (node: ASTNode) => node is TypeExtensionNode;

function isTypeNode

isTypeNode: (node: ASTNode) => node is TypeNode;

function isTypeSubTypeOf

isTypeSubTypeOf: (
    schema: GraphQLSchema,
    maybeSubType: GraphQLType,
    superType: GraphQLType
) => boolean;

Provided a type and a super type, return true if the first type is either equal or a subset of the second super type (covariant).

function isTypeSystemDefinitionNode

isTypeSystemDefinitionNode: (node: ASTNode) => node is TypeSystemDefinitionNode;

function isTypeSystemExtensionNode

isTypeSystemExtensionNode: (node: ASTNode) => node is TypeSystemExtensionNode;

function isUnionType

isUnionType: (type: unknown) => type is GraphQLUnionType;

function isValidNameError

isValidNameError: (name: string) => GraphQLError | undefined;

Returns an Error if a name is invalid.
Deprecated
Please use assertName instead. Will be removed in v17

function isValueNode

isValueNode: (node: ASTNode) => node is ValueNode;

function isWrappingType

isWrappingType: (type: unknown) => type is GraphQLWrappingType;

function KnownArgumentNamesRule

KnownArgumentNamesRule: (context: ValidationContext) => ASTVisitor;

Known argument names
A GraphQL field is only valid if all supplied arguments are defined by that field.
See https://spec.graphql.org/draft/#sec-Argument-Names See https://spec.graphql.org/draft/#sec-Directives-Are-In-Valid-Locations

function KnownDirectivesRule

KnownDirectivesRule: (
    context: ValidationContext | SDLValidationContext
) => ASTVisitor;

Known directives
A GraphQL document is only valid if all @directives are known by the schema and legally positioned.
See https://spec.graphql.org/draft/#sec-Directives-Are-Defined

function KnownFragmentNamesRule

KnownFragmentNamesRule: (context: ValidationContext) => ASTVisitor;

Known fragment names
A GraphQL document is only valid if all ...Fragment fragment spreads refer to fragments defined in the same document.
See https://spec.graphql.org/draft/#sec-Fragment-spread-target-defined

function KnownTypeNamesRule

KnownTypeNamesRule: (
    context: ValidationContext | SDLValidationContext
) => ASTVisitor;

Known type names
A GraphQL document is only valid if referenced types (specifically variable definitions and fragment conditions) are defined by the type schema.
See https://spec.graphql.org/draft/#sec-Fragment-Spread-Type-Existence

function lexicographicSortSchema

lexicographicSortSchema: (schema: GraphQLSchema) => GraphQLSchema;

Sort GraphQLSchema.
This function returns a sorted copy of the given GraphQLSchema.

function locatedError

locatedError: (
    rawOriginalError: unknown,
    nodes: ASTNode | ReadonlyArray<ASTNode> | undefined | null,
    path?: Maybe<ReadonlyArray<string | number>>
) => GraphQLError;

Given an arbitrary value, presumably thrown while attempting to execute a GraphQL operation, produce a new GraphQLError aware of the location in the document responsible for the original Error.

function LoneAnonymousOperationRule

LoneAnonymousOperationRule: (context: ASTValidationContext) => ASTVisitor;

Lone anonymous operation
A GraphQL document is only valid if when it contains an anonymous operation (the query short-hand) that it contains only that one operation definition.
See https://spec.graphql.org/draft/#sec-Lone-Anonymous-Operation

function LoneSchemaDefinitionRule

LoneSchemaDefinitionRule: (context: SDLValidationContext) => ASTVisitor;

Lone Schema definition
A GraphQL document is only valid if it contains only one schema definition.

function NoDeprecatedCustomRule

NoDeprecatedCustomRule: (context: ValidationContext) => ASTVisitor;

No deprecated
A GraphQL document is only valid if all selected fields and all used enum values have not been deprecated.
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.

function NoFragmentCyclesRule

NoFragmentCyclesRule: (context: ASTValidationContext) => ASTVisitor;

No fragment cycles
The graph of fragment spreads must not form any cycles including spreading itself. Otherwise an operation could infinitely spread or infinitely execute on cycles in the underlying data.
See https://spec.graphql.org/draft/#sec-Fragment-spreads-must-not-form-cycles

function NoSchemaIntrospectionCustomRule

NoSchemaIntrospectionCustomRule: (context: ValidationContext) => ASTVisitor;

Prohibit introspection queries
A GraphQL document is only valid if all fields selected are not fields that return an introspection type.
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.

function NoUndefinedVariablesRule

NoUndefinedVariablesRule: (context: ValidationContext) => ASTVisitor;

No undefined variables
A GraphQL operation is only valid if all variables encountered, both directly and via fragment spreads, are defined by that operation.
See https://spec.graphql.org/draft/#sec-All-Variable-Uses-Defined

function NoUnusedFragmentsRule

NoUnusedFragmentsRule: (context: ASTValidationContext) => ASTVisitor;

No unused fragments
A GraphQL document is only valid if all fragment definitions are spread within operations, or spread within other fragments spread within operations.
See https://spec.graphql.org/draft/#sec-Fragments-Must-Be-Used

function NoUnusedVariablesRule

NoUnusedVariablesRule: (context: ValidationContext) => ASTVisitor;

No unused variables
A GraphQL operation is only valid if all variables defined by an operation are used, either directly or within a spread fragment.
See https://spec.graphql.org/draft/#sec-All-Variables-Used

function OverlappingFieldsCanBeMergedRule

OverlappingFieldsCanBeMergedRule: (context: ValidationContext) => ASTVisitor;

Overlapping fields can be merged
A selection set is only valid if all fields (including spreading any fragments) either correspond to distinct response names or can be merged without ambiguity.
See https://spec.graphql.org/draft/#sec-Field-Selection-Merging

function parse

parse: (
    source: string | Source,
    options?: ParseOptions | undefined
) => DocumentNode;

Given a GraphQL source, parses it into a Document. Throws GraphQLError if a syntax error is encountered.

function parseConstValue

parseConstValue: (
    source: string | Source,
    options?: ParseOptions | undefined
) => ConstValueNode;

Similar to parseValue(), but raises a parse error if it encounters a variable. The return type will be a constant value.

function parseType

parseType: (
    source: string | Source,
    options?: ParseOptions | undefined
) => TypeNode;

Given a string containing a GraphQL Type (ex. [Int!]), parse the AST for that type. Throws GraphQLError if a syntax error is encountered.
This is useful within tools that operate upon GraphQL Types directly and in isolation of complete GraphQL documents.
Consider providing the results to the utility function: typeFromAST().

function parseValue

parseValue: (
    source: string | Source,
    options?: ParseOptions | undefined
) => ValueNode;

Given a string containing a GraphQL value (ex. [42]), parse the AST for that value. Throws GraphQLError if a syntax error is encountered.
This is useful within tools that operate upon GraphQL Values directly and in isolation of complete GraphQL documents.
Consider providing the results to the utility function: valueFromAST().

function PossibleFragmentSpreadsRule

PossibleFragmentSpreadsRule: (context: ValidationContext) => ASTVisitor;

Possible fragment spread
A fragment spread is only valid if the type condition could ever possibly be true: if there is a non-empty intersection of the possible parent types, and possible types which pass the type condition.

function PossibleTypeExtensionsRule

PossibleTypeExtensionsRule: (context: SDLValidationContext) => ASTVisitor;

Possible type extension
A type extension is only valid if the type is defined and has the same kind.

function print

print: (ast: ASTNode) => string;

Converts an AST into a string, using one set of reasonable formatting rules.

function printError

printError: (error: GraphQLError) => string;

Prints a GraphQLError to a string, representing useful location information about the error's position in the source.
Deprecated
Please use error.toString instead. Will be removed in v17

function printIntrospectionSchema

printIntrospectionSchema: (schema: GraphQLSchema) => string;

function printLocation

printLocation: (location: Location) => string;

Render a helpful description of the location in the GraphQL Source document.

function printSchema

printSchema: (schema: GraphQLSchema) => string;

function printSourceLocation

printSourceLocation: (source: Source, sourceLocation: SourceLocation) => string;

Render a helpful description of the location in the GraphQL Source document.

function printType

printType: (type: GraphQLNamedType) => string;

function ProvidedRequiredArgumentsRule

ProvidedRequiredArgumentsRule: (context: ValidationContext) => ASTVisitor;

Provided required arguments
A field or directive is only valid if all required (non-null without a default value) field arguments have been provided.

function resolveObjMapThunk

resolveObjMapThunk: <T>(thunk: ThunkObjMap<T>) => ObjMap<T>;

function resolveReadonlyArrayThunk

resolveReadonlyArrayThunk: <T>(thunk: ThunkReadonlyArray<T>) => ReadonlyArray<T>;

function responsePathAsArray

responsePathAsArray: (path: Maybe<Readonly<Path>>) => Array<string | number>;

Given a Path, return an Array of the path keys.

function ScalarLeafsRule

ScalarLeafsRule: (context: ValidationContext) => ASTVisitor;

Scalar leafs
A GraphQL document is valid only if all leaf fields (fields without sub selections) are of scalar or enum types.

function separateOperations

separateOperations: (documentAST: DocumentNode) => ObjMap<DocumentNode>;

separateOperations accepts a single AST document which may contain many operations and fragments and returns a collection of AST documents each of which contains a single operation as well the fragment definitions it refers to.

function SingleFieldSubscriptionsRule

SingleFieldSubscriptionsRule: (context: ValidationContext) => ASTVisitor;

Subscriptions must only include a non-introspection field.
A GraphQL subscription is valid only if it contains a single root field and that root field is not an introspection field.
See https://spec.graphql.org/draft/#sec-Single-root-field

function stripIgnoredCharacters

stripIgnoredCharacters: (source: string | Source) => string;

Strips characters that are not significant to the validity or execution of a GraphQL document: - UnicodeBOM - WhiteSpace - LineTerminator - Comment - Comma - BlockString indentation
Note: It is required to have a delimiter character between neighboring non-punctuator tokens and this function always uses single space as delimiter.
It is guaranteed that both input and output documents if parsed would result in the exact same AST except for nodes location.
Warning: It is guaranteed that this function will always produce stable results. However, it's not guaranteed that it will stay the same between different releases due to bugfixes or changes in the GraphQL specification.
Query example:
query SomeQuery($foo: String!, $bar: String) { someField(foo: $foo, bar: $bar) { a b { c d } } }
Becomes:
query SomeQuery($foo:String!$bar:String){someField(foo:$foo bar:$bar){a b{c d}}}
SDL example:
""" Type description """ type Foo { """ Field description """ bar: String }
Becomes:
"""Type description""" type Foo{"""Field description""" bar:String}

subscribe: (
    args: ExecutionArgs
) => Promise<AsyncGenerator<ExecutionResult, void, void> | ExecutionResult>;

Implements the "Subscribe" algorithm described in the GraphQL specification.
Returns a Promise which resolves to either an AsyncIterator (if successful) or an ExecutionResult (error). The promise will be rejected if the schema or other arguments to this function are invalid, or if the resolved event stream is not an async iterable.
If the client-provided arguments to this function do not result in a compliant subscription, a GraphQL Response (ExecutionResult) with descriptive errors and no data will be returned.
If the source stream could not be created due to faulty subscription resolver logic or underlying systems, the promise will resolve to a single ExecutionResult containing errors and no data.
If the operation succeeded, the promise resolves to an AsyncIterator, which yields a stream of ExecutionResults representing the response stream.
Accepts either an object with named arguments, or individual arguments.

function syntaxError

syntaxError: (
    source: Source,
    position: number,
    description: string
) => GraphQLError;

Produces a GraphQLError representing a syntax error, containing useful descriptive information about the syntax error's position in the source.

function typeFromAST

typeFromAST: {
    (schema: GraphQLSchema, typeNode: NamedTypeNode): GraphQLNamedType | undefined;
    (schema: GraphQLSchema, typeNode: ListTypeNode): GraphQLList<any>;
    (schema: GraphQLSchema, typeNode: NonNullTypeNode): GraphQLNonNull<any>;
    (schema: GraphQLSchema, typeNode: TypeNode): GraphQLType;
};

Given a Schema and an AST node describing a type, return a GraphQLType definition which applies to that type. For example, if provided the parsed AST node for [User], a GraphQLList instance will be returned, containing the type called "User" found in the schema. If a type called "User" is not found in the schema, then undefined will be returned.

function UniqueArgumentDefinitionNamesRule

UniqueArgumentDefinitionNamesRule: (context: SDLValidationContext) => ASTVisitor;

Unique argument definition names
A GraphQL Object or Interface type is only valid if all its fields have uniquely named arguments. A GraphQL Directive is only valid if all its arguments are uniquely named.

function UniqueArgumentNamesRule

UniqueArgumentNamesRule: (context: ASTValidationContext) => ASTVisitor;

Unique argument names
A GraphQL field or directive is only valid if all supplied arguments are uniquely named.
See https://spec.graphql.org/draft/#sec-Argument-Names

function UniqueDirectiveNamesRule

UniqueDirectiveNamesRule: (context: SDLValidationContext) => ASTVisitor;

Unique directive names
A GraphQL document is only valid if all defined directives have unique names.

function UniqueDirectivesPerLocationRule

UniqueDirectivesPerLocationRule: (
    context: ValidationContext | SDLValidationContext
) => ASTVisitor;

Unique directive names per location
A GraphQL document is only valid if all non-repeatable directives at a given location are uniquely named.
See https://spec.graphql.org/draft/#sec-Directives-Are-Unique-Per-Location

function UniqueEnumValueNamesRule

UniqueEnumValueNamesRule: (context: SDLValidationContext) => ASTVisitor;

Unique enum value names
A GraphQL enum type is only valid if all its values are uniquely named.

function UniqueFieldDefinitionNamesRule

UniqueFieldDefinitionNamesRule: (context: SDLValidationContext) => ASTVisitor;

Unique field definition names
A GraphQL complex type is only valid if all its fields are uniquely named.

function UniqueFragmentNamesRule

UniqueFragmentNamesRule: (context: ASTValidationContext) => ASTVisitor;

Unique fragment names
A GraphQL document is only valid if all defined fragments have unique names.
See https://spec.graphql.org/draft/#sec-Fragment-Name-Uniqueness

function UniqueInputFieldNamesRule

UniqueInputFieldNamesRule: (context: ASTValidationContext) => ASTVisitor;

Unique input field names
A GraphQL input object value is only valid if all supplied fields are uniquely named.
See https://spec.graphql.org/draft/#sec-Input-Object-Field-Uniqueness

function UniqueOperationNamesRule

UniqueOperationNamesRule: (context: ASTValidationContext) => ASTVisitor;

Unique operation names
A GraphQL document is only valid if all defined operations have unique names.
See https://spec.graphql.org/draft/#sec-Operation-Name-Uniqueness

function UniqueOperationTypesRule

UniqueOperationTypesRule: (context: SDLValidationContext) => ASTVisitor;

Unique operation types
A GraphQL document is only valid if it has only one type per operation.

function UniqueTypeNamesRule

UniqueTypeNamesRule: (context: SDLValidationContext) => ASTVisitor;

Unique type names
A GraphQL document is only valid if all defined types have unique names.

function UniqueVariableNamesRule

UniqueVariableNamesRule: (context: ASTValidationContext) => ASTVisitor;

Unique variable names
A GraphQL operation is only valid if all its variables are uniquely named.

function validate

validate: (
    schema: GraphQLSchema,
    documentAST: DocumentNode,
    rules?: ReadonlyArray<ValidationRule>,
    options?: { maxErrors?: number },
    typeInfo?: TypeInfo
) => ReadonlyArray<GraphQLError>;

Implements the "Validation" section of the spec.
Validation runs synchronously, returning an array of encountered errors, or an empty array if no errors were encountered and the document is valid.
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 (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.
Optionally a custom TypeInfo instance may be provided. If not provided, one will be created from the provided schema.

function validateSchema

validateSchema: (schema: GraphQLSchema) => ReadonlyArray<GraphQLError>;

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 valueFromAST

valueFromAST: (
    valueNode: Maybe<ValueNode>,
    type: GraphQLInputType,
    variables?: Maybe<ObjMap<unknown>>
) => unknown;

Produces a JavaScript value given a GraphQL Value AST.
A GraphQL type must be provided, which will be used to interpret different GraphQL Value literals.
Returns undefined when the value could not be validly coerced according to the provided type.
| GraphQL Value | JSON Value | | -------------------- | ------------- | | Input Object | Object | | List | Array | | Boolean | Boolean | | String | String | | Int / Float | Number | | Enum Value | Unknown | | NullValue | null |

function valueFromASTUntyped

valueFromASTUntyped: (
    valueNode: ValueNode,
    variables?: Maybe<ObjMap<unknown>>
) => unknown;

Produces a JavaScript value given a GraphQL Value AST.
Unlike valueFromAST(), no type is provided. The resulting JavaScript value will reflect the provided GraphQL value AST.
| GraphQL Value | JavaScript Value | | -------------------- | ---------------- | | Input Object | Object | | List | Array | | Boolean | Boolean | | String / Enum | String | | Int / Float | Number | | Null | null |

function ValuesOfCorrectTypeRule

ValuesOfCorrectTypeRule: (context: ValidationContext) => ASTVisitor;

Value literals of correct type
A GraphQL document is only valid if all value literals are of the type expected at their position.
See https://spec.graphql.org/draft/#sec-Values-of-Correct-Type

function VariablesAreInputTypesRule

VariablesAreInputTypesRule: (context: ValidationContext) => ASTVisitor;

Variables are input types
A GraphQL operation is only valid if all the variables it defines are of input types (scalar, enum, or input object).
See https://spec.graphql.org/draft/#sec-Variables-Are-Input-Types

function VariablesInAllowedPositionRule

VariablesInAllowedPositionRule: (context: ValidationContext) => ASTVisitor;

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

function visit

visit: {
    <N extends ASTNode>(
        root: N,
        visitor: ASTVisitor,
        visitorKeys?: ASTVisitorKeyMap
    ): N;
    <R>(root: ASTNode, visitor: ASTReducer<R>, visitorKeys?: ASTVisitorKeyMap): R;
};

visit() will walk through an AST using a depth-first traversal, calling the visitor's enter function at each node in the traversal, and calling the leave function after visiting that node and all of its child nodes.
By returning different values from the enter and leave functions, the behavior of the visitor can be altered, including skipping over a sub-tree of the AST (by returning false), editing the AST by returning a value or null to remove the value, or to stop the whole traversal by returning BREAK.
When using visit() to edit an AST, the original AST will not be modified, and a new version of the AST with the changes applied will be returned from the visit function.
const editedAST = visit(ast, { enter(node, key, parent, path, ancestors) { // @return // undefined: no action // false: skip visiting this node // visitor.BREAK: stop visiting altogether // null: delete this node // any value: replace this node with the returned value }, leave(node, key, parent, path, ancestors) { // @return // undefined: no action // false: no action // visitor.BREAK: stop visiting altogether // null: delete this node // any value: replace this node with the returned value } });
Alternatively to providing enter() and leave() functions, a visitor can instead provide functions named the same as the kinds of AST nodes, or enter/leave visitors at a named key, leading to three permutations of the visitor API:
1) Named visitors triggered when entering a node of a specific kind.
visit(ast, { Kind(node) { // enter the "Kind" node } })
2) Named visitors that trigger upon entering and leaving a node of a specific kind.
visit(ast, { Kind: { enter(node) { // enter the "Kind" node } leave(node) { // leave the "Kind" node } } })
3) Generic visitors that trigger upon entering and leaving any node.
visit(ast, { enter(node) { // enter any node }, leave(node) { // leave any node } })

function visitInParallel

visitInParallel: (visitors: ReadonlyArray<ASTVisitor>) => ASTVisitor;

Creates a new visitor instance which delegates to many visitors to run in parallel. Each visitor will be visited for each node before moving on.
If a prior visitor edits a node, no following visitors will see that node.

function visitWithTypeInfo

visitWithTypeInfo: (typeInfo: TypeInfo, visitor: ASTVisitor) => ASTVisitor;

Creates a new visitor instance which maintains a provided TypeInfo instance along with visiting visitor.

Classes

class GraphQLDirective

class GraphQLDirective {}

Directives are used by the GraphQL runtime as a way of modifying execution behavior. Type system creators will usually not create these directly.

constructor

constructor(config: Readonly<GraphQLDirectiveConfig>);

property [Symbol.toStringTag]

readonly [Symbol.toStringTag]: string;

property args

args: readonly GraphQLArgument[];

property astNode

astNode: DirectiveDefinitionNode;

property description

description: string;

property extensions

extensions: Readonly<GraphQLDirectiveExtensions>;

property isRepeatable

isRepeatable: boolean;

property locations

locations: readonly DirectiveLocation[];

property name

name: string;

method toConfig

toConfig: () => GraphQLDirectiveNormalizedConfig;

method toJSON

toJSON: () => string;

method toString

toString: () => string;

class GraphQLEnumType

class GraphQLEnumType {}

Enum Type Definition
Some leaf values of requests and input values are Enums. GraphQL serializes Enum values as strings, however internally Enums can be represented by any kind of type, often integers.
Example:
const RGBType = new GraphQLEnumType({ name: 'RGB', values: { RED: { value: 0 }, GREEN: { value: 1 }, BLUE: { value: 2 } } });
Note: If a value is not provided in a definition, the name of the enum value will be used as its internal value.

constructor

constructor(config: Readonly<GraphQLEnumTypeConfig>);

property [Symbol.toStringTag]

readonly [Symbol.toStringTag]: string;

property astNode

astNode: EnumTypeDefinitionNode;

property description

description: string;

property extensionASTNodes

extensionASTNodes: readonly EnumTypeExtensionNode[];

property extensions

extensions: Readonly<GraphQLEnumTypeExtensions>;

property name

name: string;

method getValue

getValue: (name: string) => Maybe<GraphQLEnumValue>;

method getValues

getValues: () => ReadonlyArray<GraphQLEnumValue>;

method parseLiteral

parseLiteral: (
    valueNode: ValueNode,
    _variables: Maybe<ObjMap<unknown>>
) => Maybe<any>;

method parseValue

parseValue: (inputValue: unknown) => Maybe<any>;

method serialize

serialize: (outputValue: unknown) => Maybe<string>;

method toConfig

toConfig: () => GraphQLEnumTypeNormalizedConfig;

method toJSON

toJSON: () => string;

method toString

toString: () => string;

class GraphQLError

class GraphQLError extends Error {}

A GraphQLError describes an Error found during the parse, validate, or execute phases of performing a GraphQL operation. In addition to a message and stack trace, it also includes information about the locations in a GraphQL document and/or execution result that correspond to the Error.

constructor

constructor(message: string, options?: GraphQLErrorOptions);

constructor

constructor(
    message: string,
    nodes?: ASTNode | readonly ASTNode[],
    source?: Source,
    positions?: readonly number[],
    path?: readonly (string | number)[],
    originalError?: Error & { readonly extensions?: unknown },
    extensions?: GraphQLErrorExtensions
);

Deprecated
Please use the GraphQLErrorOptions constructor overload instead.

property [Symbol.toStringTag]

readonly [Symbol.toStringTag]: string;

property extensions

readonly extensions: GraphQLErrorExtensions;

Extension fields to add to the formatted error.

property locations

readonly locations: readonly SourceLocation[];

An array of { line, column } locations within the source GraphQL document which correspond to this error.
Errors during validation often contain multiple locations, for example to point out two things with the same name. Errors during execution include a single location, the field which produced the error.
Enumerable, and appears in the result of JSON.stringify().

property nodes

readonly nodes: readonly ASTNode[];

An array of GraphQL AST Nodes corresponding to this error.

property originalError

readonly originalError: Error;

The original error thrown from a field resolver during execution.

property path

readonly path: readonly (string | number)[];

An array describing the JSON-path into the execution response which corresponds to this error. Only included for errors during execution.
Enumerable, and appears in the result of JSON.stringify().

property positions

readonly positions: readonly number[];

An array of character offsets within the source GraphQL document which correspond to this error.

property source

readonly source: Source;

The source GraphQL document for the first location of this error.
Note that if this Error represents more than one node, the source may not represent nodes after the first node.

method toJSON

toJSON: () => GraphQLFormattedError;

method toString

toString: () => string;

class GraphQLInputObjectType

class GraphQLInputObjectType {}

Input Object Type Definition

An input object defines a structured collection of fields which may be supplied to a field argument.

Using NonNull will ensure that a value must be provided by the query

Example:

const GeoPoint = new GraphQLInputObjectType({
  name: 'GeoPoint',
  fields: {
    lat: { type: new GraphQLNonNull(GraphQLFloat) },
    lon: { type: new GraphQLNonNull(GraphQLFloat) },
    alt: { type: GraphQLFloat, defaultValue: 0 },
  }
});

constructor

constructor(config: Readonly<GraphQLInputObjectTypeConfig>);

property [Symbol.toStringTag]

readonly [Symbol.toStringTag]: string;

property astNode

astNode: InputObjectTypeDefinitionNode;

property description

description: string;

property extensionASTNodes

extensionASTNodes: readonly InputObjectTypeExtensionNode[];

property extensions

extensions: Readonly<GraphQLInputObjectTypeExtensions>;

property name

name: string;

method getFields

getFields: () => GraphQLInputFieldMap;

method toConfig

toConfig: () => GraphQLInputObjectTypeNormalizedConfig;

method toJSON

toJSON: () => string;

method toString

toString: () => string;

class GraphQLInterfaceType

class GraphQLInterfaceType {}

Interface Type Definition
When a field can return one of a heterogeneous set of types, a Interface type is used to describe what types are possible, what fields are in common across all types, as well as a function to determine which type is actually used when the field is resolved.
Example:
const EntityType = new GraphQLInterfaceType({ name: 'Entity', fields: { name: { type: GraphQLString } } });

constructor

constructor(config: Readonly<GraphQLInterfaceTypeConfig<any, any>>);

property [Symbol.toStringTag]

readonly [Symbol.toStringTag]: string;

property astNode

astNode: InterfaceTypeDefinitionNode;

property description

description: string;

property extensionASTNodes

extensionASTNodes: readonly InterfaceTypeExtensionNode[];

property extensions

extensions: Readonly<GraphQLInterfaceTypeExtensions>;

property name

name: string;

property resolveType

resolveType: GraphQLTypeResolver<any, any>;

method getFields

getFields: () => GraphQLFieldMap<any, any>;

method getInterfaces

getInterfaces: () => ReadonlyArray<GraphQLInterfaceType>;

method toConfig

toConfig: () => GraphQLInterfaceTypeNormalizedConfig;

method toJSON

toJSON: () => string;

method toString

toString: () => string;

class GraphQLList

class GraphQLList<T extends GraphQLType> {}

List Type Wrapper

A list is a wrapping type which points to another type. Lists are often created within the context of defining the fields of an object type.

Example:

const PersonType = new GraphQLObjectType({
  name: 'Person',
  fields: () => ({
    parents: { type: new GraphQLList(PersonType) },
    children: { type: new GraphQLList(PersonType) },
  })
})

constructor

constructor(ofType: GraphQLType);

property [Symbol.toStringTag]

readonly [Symbol.toStringTag]: string;

property ofType

readonly ofType: GraphQLType;

method toJSON

toJSON: () => string;

method toString

toString: () => string;

class GraphQLNonNull

class GraphQLNonNull<T extends GraphQLNullableType> {}

Non-Null Type Wrapper
A non-null is a wrapping type which points to another type. Non-null types enforce that their values are never null and can ensure an error is raised if this ever occurs during a request. It is useful for fields which you can make a strong guarantee on non-nullability, for example usually the id field of a database row will never be null.
Example:
const RowType = new GraphQLObjectType({ name: 'Row', fields: () => ({ id: { type: new GraphQLNonNull(GraphQLString) }, }) })
Note: the enforcement of non-nullability occurs within the executor.

constructor

constructor(ofType: GraphQLNullableType);

property [Symbol.toStringTag]

readonly [Symbol.toStringTag]: string;

property ofType

readonly ofType: GraphQLNullableType;

method toJSON

toJSON: () => string;

method toString

toString: () => string;

class GraphQLObjectType

class GraphQLObjectType<TSource = any, TContext = any> {}

Object Type Definition

Almost all of the GraphQL types you define will be object types. Object types have a name, but most importantly describe their fields.

Example:

const AddressType = new GraphQLObjectType({
  name: 'Address',
  fields: {
    street: { type: GraphQLString },
    number: { type: GraphQLInt },
    formatted: {
      type: GraphQLString,
      resolve(obj) {
        return obj.number + ' ' + obj.street
      }
    }
  }
});

When two types need to refer to each other, or a type needs to refer to itself in a field, you can use a function expression (aka a closure or a thunk) to supply the fields lazily.

Example:

const PersonType = new GraphQLObjectType({
  name: 'Person',
  fields: () => ({
    name: { type: GraphQLString },
    bestFriend: { type: PersonType },
  })
});

constructor

constructor(config: Readonly<GraphQLObjectTypeConfig<TSource, TContext>>);

property [Symbol.toStringTag]

readonly [Symbol.toStringTag]: string;

property astNode

astNode: ObjectTypeDefinitionNode;

property description

description: string;

property extensionASTNodes

extensionASTNodes: readonly ObjectTypeExtensionNode[];

property extensions

extensions: Readonly<GraphQLObjectTypeExtensions<TSource, TContext>>;

property isTypeOf

isTypeOf: GraphQLIsTypeOfFn<TSource, TContext>;

property name

name: string;

method getFields

getFields: () => GraphQLFieldMap<TSource, TContext>;

method getInterfaces

getInterfaces: () => ReadonlyArray<GraphQLInterfaceType>;

method toConfig

toConfig: () => GraphQLObjectTypeNormalizedConfig<TSource, TContext>;

method toJSON

toJSON: () => string;

method toString

toString: () => string;

class GraphQLScalarType

class GraphQLScalarType<TInternal = unknown, TExternal = TInternal> {}

Scalar Type Definition
The leaf values of any request and input values to arguments are Scalars (or Enums) and are defined with a name and a series of functions used to parse input from ast or variables and to ensure validity.
If a type's serialize function returns null or does not return a value (i.e. it returns undefined) then an error will be raised and a null value will be returned in the response. It is always better to validate
Example:
const OddType = new GraphQLScalarType({ name: 'Odd', serialize(value) { if (!Number.isFinite(value)) { throw new Error( `Scalar "Odd" cannot represent "${value}" since it is not a finite number.`, ); } if (value % 2 === 0) { throw new Error(`Scalar "Odd" cannot represent "${value}" since it is even.`); } return value; } });

constructor

constructor(config: Readonly<GraphQLScalarTypeConfig<TInternal, TExternal>>);

property [Symbol.toStringTag]

readonly [Symbol.toStringTag]: string;

property astNode

astNode: ScalarTypeDefinitionNode;

property description

description: string;

property extensionASTNodes

extensionASTNodes: readonly ScalarTypeExtensionNode[];

property extensions

extensions: Readonly<GraphQLScalarTypeExtensions>;

property name

name: string;

property parseLiteral

parseLiteral: GraphQLScalarLiteralParser<TInternal>;

property parseValue

parseValue: GraphQLScalarValueParser<TInternal>;

property serialize

serialize: GraphQLScalarSerializer<TExternal>;

property specifiedByURL

specifiedByURL: string;

method toConfig

toConfig: () => GraphQLScalarTypeNormalizedConfig<TInternal, TExternal>;

method toJSON

toJSON: () => string;

method toString

toString: () => string;

class GraphQLSchema

class GraphQLSchema {}

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:

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:

const characterInterface = new GraphQLInterfaceType({
  name: 'Character',
  ...
});

const humanType = new GraphQLObjectType({
  name: 'Human',
  interfaces: [characterInterface],
  ...
});

const droidType = new GraphQLObjectType({
  name: 'Droid',
  interfaces: [characterInterface],
  ...
});

const schema = new GraphQLSchema({
  query: new GraphQLObjectType({
    name: 'Query',
    fields: {
      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 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:

const MyAppSchema = new GraphQLSchema({
  ...
  directives: specifiedDirectives.concat([ myCustomDirective ]),
})

constructor

constructor(config: Readonly<GraphQLSchemaConfig>);

property [Symbol.toStringTag]

readonly [Symbol.toStringTag]: string;

property astNode

astNode: SchemaDefinitionNode;

property description

description: string;

property extensionASTNodes

extensionASTNodes: readonly SchemaExtensionNode[];

property extensions

extensions: Readonly<GraphQLSchemaExtensions>;

method getDirective

getDirective: (name: string) => Maybe<GraphQLDirective>;

method getDirectives

getDirectives: () => ReadonlyArray<GraphQLDirective>;

method getImplementations

getImplementations: (interfaceType: GraphQLInterfaceType) => {
    objects: ReadonlyArray<GraphQLObjectType>;
    interfaces: ReadonlyArray<GraphQLInterfaceType>;
};

method getMutationType

getMutationType: () => Maybe<GraphQLObjectType>;

method getPossibleTypes

getPossibleTypes: (
    abstractType: GraphQLAbstractType
) => ReadonlyArray<GraphQLObjectType>;

method getQueryType

getQueryType: () => Maybe<GraphQLObjectType>;

method getRootType

getRootType: (operation: OperationTypeNode) => Maybe<GraphQLObjectType>;

method getSubscriptionType

getSubscriptionType: () => Maybe<GraphQLObjectType>;

method getType

getType: (name: string) => GraphQLNamedType | undefined;

method getTypeMap

getTypeMap: () => TypeMap;

method isSubType

isSubType: (
    abstractType: GraphQLAbstractType,
    maybeSubType: GraphQLObjectType | GraphQLInterfaceType
) => boolean;

method toConfig

toConfig: () => GraphQLSchemaNormalizedConfig;

class GraphQLUnionType

class GraphQLUnionType {}

Union Type Definition

When a field can return one of a heterogeneous set of types, a Union type is used to describe what types are possible as well as providing a function to determine which type is actually used when the field is resolved.

Example:

const PetType = new GraphQLUnionType({
  name: 'Pet',
  types: [ DogType, CatType ],
  resolveType(value) {
    if (value instanceof Dog) {
      return DogType;
    }
    if (value instanceof Cat) {
      return CatType;
    }
  }
});

constructor

constructor(config: Readonly<GraphQLUnionTypeConfig<any, any>>);

property [Symbol.toStringTag]

readonly [Symbol.toStringTag]: string;

property astNode

astNode: UnionTypeDefinitionNode;

property description

description: string;

property extensionASTNodes

extensionASTNodes: readonly UnionTypeExtensionNode[];

property extensions

extensions: Readonly<GraphQLUnionTypeExtensions>;

property name

name: string;

property resolveType

resolveType: GraphQLTypeResolver<any, any>;

method getTypes

getTypes: () => ReadonlyArray<GraphQLObjectType>;

method toConfig

toConfig: () => GraphQLUnionTypeNormalizedConfig;

method toJSON

toJSON: () => string;

method toString

toString: () => string;

class Lexer

class Lexer {}

Given a Source object, creates a Lexer for that source. A Lexer is a stateful stream generator in that every time it is advanced, it returns the next token in the Source. Assuming the source lexes, the final Token emitted by the lexer will be of kind EOF, after which the lexer will repeatedly return the same EOF token whenever called.

constructor

constructor(source: Source);

property [Symbol.toStringTag]

readonly [Symbol.toStringTag]: string;

property lastToken

lastToken: Token;

The previously focused non-ignored token.

property line

line: number;

The (1-indexed) line containing the current token.

property lineStart

lineStart: number;

The character offset at which the current line begins.

property source

source: Source;

property token

token: Token;

The currently focused non-ignored token.

method advance

advance: () => Token;

Advances the token stream to the next non-ignored token.

method lookahead

lookahead: () => Token;

Looks ahead and returns the next non-ignored token, but does not change the state of Lexer.

class Location

class Location {}

Contains a range of UTF-8 character offsets and token references that identify the region of the source from which the AST derived.

constructor

constructor(startToken: Token, endToken: Token, source: Source);

property [Symbol.toStringTag]

readonly [Symbol.toStringTag]: string;

property end

readonly end: number;

The character offset at which this Node ends.

property endToken

readonly endToken: Token;

The Token at which this Node ends.

property source

readonly source: Source;

The Source document the AST represents.

property start

readonly start: number;

The character offset at which this Node begins.

property startToken

readonly startToken: Token;

The Token at which this Node begins.

method toJSON

toJSON: () => { start: number; end: number };

class Source

class Source {}

A representation of source input to GraphQL. The name and locationOffset parameters are optional, but they are useful for clients who store GraphQL documents in source files. For example, if the GraphQL input starts at line 40 in a file named Foo.graphql, it might be useful for name to be "Foo.graphql" and location to be { line: 40, column: 1 }. The line and column properties in locationOffset are 1-indexed.

constructor

constructor(body: string, name?: string, locationOffset?: Location);

property [Symbol.toStringTag]

readonly [Symbol.toStringTag]: string;

property body

body: string;

property locationOffset

locationOffset: Location;

property name

name: string;

class Token

class Token {}

Represents a range of characters represented by a lexical token within a Source.

constructor

constructor(
    kind: TokenKind,
    start: number,
    end: number,
    line: number,
    column: number,
    value?: string
);

property [Symbol.toStringTag]

readonly [Symbol.toStringTag]: string;

property column

readonly column: number;

The 1-indexed column number at which this Token begins.

property end

readonly end: number;

The character offset at which this Node ends.

property kind

readonly kind: TokenKind;

The kind of Token.

property line

readonly line: number;

The 1-indexed line number on which this Token appears.

property next

readonly next: Token;

property prev

readonly prev: Token;

Tokens exist as nodes in a double-linked-list amongst all tokens including ignored tokens. is always the first node and the last.

property start

readonly start: number;

The character offset at which this Node begins.

property value

readonly value: string;

For non-punctuation tokens, represents the interpreted value of the token.
Note: is undefined for punctuation tokens, but typed as string for convenience in the parser.

method toJSON

toJSON: () => { kind: TokenKind; value?: string; line: number; column: number };

class TypeInfo

class TypeInfo {}

TypeInfo is a utility class which, given a GraphQL schema, can keep track of the current field and type definitions at any point in a GraphQL document AST during a recursive descent by calling enter(node) and leave(node).

constructor

constructor(
    schema: GraphQLSchema,
    initialType?: GraphQLType,
    getFieldDefFn?: GetFieldDefFn
);

property [Symbol.toStringTag]

readonly [Symbol.toStringTag]: string;

method enter

enter: (node: ASTNode) => void;

method getArgument

getArgument: () => Maybe<GraphQLArgument>;

method getDefaultValue

getDefaultValue: () => Maybe<unknown>;

method getDirective

getDirective: () => Maybe<GraphQLDirective>;

method getEnumValue

getEnumValue: () => Maybe<GraphQLEnumValue>;

method getFieldDef

getFieldDef: () => GraphQLField<unknown, unknown, any>;

method getInputType

getInputType: () => Maybe<GraphQLInputType>;

method getParentInputType

getParentInputType: () => Maybe<GraphQLInputType>;

method getParentType

getParentType: () => Maybe<GraphQLCompositeType>;

method getType

getType: () => Maybe<GraphQLOutputType>;

method leave

leave: (node: ASTNode) => void;

class ValidationContext

class ValidationContext extends ASTValidationContext {}

constructor

constructor(
    schema: GraphQLSchema,
    ast: DocumentNode,
    typeInfo: TypeInfo,
    onError: (error: GraphQLError) => void
);

property [Symbol.toStringTag]

readonly [Symbol.toStringTag]: string;

method getArgument

getArgument: () => Maybe<GraphQLArgument>;

method getDirective

getDirective: () => Maybe<GraphQLDirective>;

method getEnumValue

getEnumValue: () => Maybe<GraphQLEnumValue>;

method getFieldDef

getFieldDef: () => GraphQLField<unknown, unknown, any>;

method getInputType

getInputType: () => Maybe<GraphQLInputType>;

method getParentInputType

getParentInputType: () => Maybe<GraphQLInputType>;

method getParentType

getParentType: () => Maybe<GraphQLCompositeType>;

method getRecursiveVariableUsages

getRecursiveVariableUsages: (
    operation: OperationDefinitionNode
) => ReadonlyArray<VariableUsage>;

method getSchema

getSchema: () => GraphQLSchema;

method getType

getType: () => Maybe<GraphQLOutputType>;

method getVariableUsages

getVariableUsages: (node: NodeWithSelectionSet) => ReadonlyArray<VariableUsage>;

Interfaces

interface ArgumentNode

interface ArgumentNode {}

property kind

readonly kind: Kind.ARGUMENT;

property loc

readonly loc?: Location;

property name

readonly name: NameNode;

property value

readonly value: ValueNode;

interface BooleanValueNode

interface BooleanValueNode {}

property kind

readonly kind: Kind.BOOLEAN;

property loc

readonly loc?: Location;

property value

readonly value: boolean;

interface BreakingChange

interface BreakingChange {}

property description

description: string;

property type

type: BreakingChangeType;

interface BuildSchemaOptions

interface BuildSchemaOptions extends GraphQLSchemaValidationOptions {}

property assumeValidSDL

assumeValidSDL?: boolean;

Set to true to assume the SDL is valid.
Default: false

interface ConstArgumentNode

interface ConstArgumentNode {}

property kind

readonly kind: Kind.ARGUMENT;

property loc

readonly loc?: Location;

property name

readonly name: NameNode;

property value

readonly value: ConstValueNode;

interface ConstDirectiveNode

interface ConstDirectiveNode {}

property arguments

readonly arguments?: ReadonlyArray<ConstArgumentNode>;

property kind

readonly kind: Kind.DIRECTIVE;

property loc

readonly loc?: Location;

property name

readonly name: NameNode;

interface ConstListValueNode

interface ConstListValueNode {}

property kind

readonly kind: Kind.LIST;

property loc

readonly loc?: Location;

property values

readonly values: ReadonlyArray<ConstValueNode>;

interface ConstObjectFieldNode

interface ConstObjectFieldNode {}

property kind

readonly kind: Kind.OBJECT_FIELD;

property loc

readonly loc?: Location;

property name

readonly name: NameNode;

property value

readonly value: ConstValueNode;

interface ConstObjectValueNode

interface ConstObjectValueNode {}

property fields

readonly fields: ReadonlyArray<ConstObjectFieldNode>;

property kind

readonly kind: Kind.OBJECT;

property loc

readonly loc?: Location;

interface DangerousChange

interface DangerousChange {}

property description

description: string;

property type

type: DangerousChangeType;

interface DirectiveDefinitionNode

interface DirectiveDefinitionNode {}

Directive Definitions

property arguments

readonly arguments?: ReadonlyArray<InputValueDefinitionNode>;

property description

readonly description?: StringValueNode;

property kind

readonly kind: Kind.DIRECTIVE_DEFINITION;

property loc

readonly loc?: Location;

property locations

readonly locations: ReadonlyArray<NameNode>;

property name

readonly name: NameNode;

property repeatable

readonly repeatable: boolean;

interface DirectiveNode

interface DirectiveNode {}

Directives

property arguments

readonly arguments?: ReadonlyArray<ArgumentNode>;

property kind

readonly kind: Kind.DIRECTIVE;

property loc

readonly loc?: Location;

property name

readonly name: NameNode;

interface DocumentNode

interface DocumentNode {}

Document

property definitions

readonly definitions: ReadonlyArray<DefinitionNode>;

property kind

readonly kind: Kind.DOCUMENT;

property loc

readonly loc?: Location;

interface EnumTypeDefinitionNode

interface EnumTypeDefinitionNode {}

property description

readonly description?: StringValueNode;

property directives

readonly directives?: ReadonlyArray<ConstDirectiveNode>;

property kind

readonly kind: Kind.ENUM_TYPE_DEFINITION;

property loc

readonly loc?: Location;

property name

readonly name: NameNode;

property values

readonly values?: ReadonlyArray<EnumValueDefinitionNode>;

interface EnumTypeExtensionNode

interface EnumTypeExtensionNode {}

property directives

readonly directives?: ReadonlyArray<ConstDirectiveNode>;

property kind

readonly kind: Kind.ENUM_TYPE_EXTENSION;

property loc

readonly loc?: Location;

property name

readonly name: NameNode;

property values

readonly values?: ReadonlyArray<EnumValueDefinitionNode>;

interface EnumValueDefinitionNode

interface EnumValueDefinitionNode {}

property description

readonly description?: StringValueNode;

property directives

readonly directives?: ReadonlyArray<ConstDirectiveNode>;

property kind

readonly kind: Kind.ENUM_VALUE_DEFINITION;

property loc

readonly loc?: Location;

property name

readonly name: NameNode;

interface EnumValueNode

interface EnumValueNode {}

property kind

readonly kind: Kind.ENUM;

property loc

readonly loc?: Location;

property value

readonly value: string;

interface ExecutionArgs

interface ExecutionArgs {}

property contextValue

contextValue?: unknown;

property document

document: DocumentNode;

property fieldResolver

fieldResolver?: Maybe<GraphQLFieldResolver<any, any>>;

property operationName

operationName?: Maybe<string>;

property rootValue

rootValue?: unknown;

property schema

schema: GraphQLSchema;

property subscribeFieldResolver

subscribeFieldResolver?: Maybe<GraphQLFieldResolver<any, any>>;

property typeResolver

typeResolver?: Maybe<GraphQLTypeResolver<any, any>>;

property variableValues

variableValues?: Maybe<{
    readonly [variable: string]: unknown;
}>;

interface ExecutionResult

interface ExecutionResult<TData = ObjMap<unknown>, TExtensions = ObjMap<unknown>>

graphql

Install

Overview

Index

Variables

Functions

Classes

Interfaces

Enums

Type Aliases

Variables

variable BREAK

variable DEFAULT_DEPRECATION_REASON

variable defaultFieldResolver

variable defaultTypeResolver

variable GRAPHQL_MAX_INT

variable GRAPHQL_MIN_INT

variable GraphQLBoolean

variable GraphQLDeprecatedDirective

variable GraphQLFloat

variable GraphQLID

variable GraphQLIncludeDirective

variable GraphQLInt

variable GraphQLSkipDirective

variable GraphQLSpecifiedByDirective

variable GraphQLString

variable introspectionTypes

variable SchemaMetaFieldDef

variable specifiedDirectives

variable specifiedRules

variable specifiedScalarTypes

variable TypeMetaFieldDef

variable TypeNameMetaFieldDef

variable version

variable versionInfo

Functions

function assertAbstractType

function assertCompositeType

function assertDirective

function assertEnumType

function assertInputObjectType

function assertInputType

function assertInterfaceType

function assertLeafType

function assertListType

function assertName

function assertNamedType

function assertNonNullType

function assertNullableType

function assertObjectType

function assertOutputType

function assertScalarType

function assertSchema

function assertType

function assertUnionType

function assertValidName

Deprecated

function assertValidSchema

function assertWrappingType

function astFromValue

function buildASTSchema

function buildClientSchema

function buildSchema

function coerceInputValue

function concatAST

function createSourceEventStream

Deprecated

function doTypesOverlap

function ExecutableDefinitionsRule

function execute

function executeSync

function extendSchema

function FieldsOnCorrectTypeRule

function findBreakingChanges

function findDangerousChanges

function formatError

Deprecated

function FragmentsOnCompositeTypesRule

function getArgumentValues

function getDirectiveValues