9/13/2020 graphql/type | API Reference
GraphQL Learn Code Community Spec Code of Conduct Foundation Landscape
Search docs...
graphql/type [Link] TUTORIAL
Getting Started
The graphql/type module is responsible for de ning GraphQL types and schema.
Running Express +
You can import either from the graphql/type module, or from the root graphql
GraphQL
module. For example:
GraphQL Clients
import { GraphQLSchema } from 'graphql'; // ES6 Basic Types
var { GraphQLSchema } = require('graphql'); // CommonJS
Passing Arguments
Object Types
Mutations and Input
Overview Types
Schema Authentication &
Middleware
class GraphQLSchema
A representation of the capabilities of a GraphQL Server.
ADVANCED GUIDES
De nitions
Constructing Types
class GraphQLScalarType
A scalar type within GraphQL.
API REFERENCE
class GraphQLObjectType
An object type within GraphQL that contains elds.
express-graphql
class GraphQLInterfaceType graphqlHTTP
An interface type within GraphQL that de nes elds implementations will contain.
graphql
class GraphQLUnionType
A union type within GraphQL that de nes a list of implementations. graphql
class GraphQLEnumType
graphql/error
An enum type within GraphQL that de nes a list of valid values.
formatError
class GraphQLInputObjectType GraphQLError
An input object type within GraphQL that represents structured inputs.
locatedError
syntaxError
class GraphQLList
A type wrapper around other types that represents a list of those types.
graphql/execution
# class GraphQLNonNull
A type wrapper around other types that represents a non-null version of those types. execute
graphql/language
Predicates BREAK
[Link] 1/11
9/13/2020 graphql/type | API Reference
function isInputType getLocation
Returns if a type can be used as input types for arguments and directives. Kind
lex
function isOutputType parse
Returns if a type can be used as output types as the result of elds.
parseValue
function isLeafType printSource
Returns if a type can be a leaf value in a response. visit
function isCompositeType graphql/type
Returns if a type can be the parent context of a selection set.
getNamedType
function isAbstractType getNullableType
Returns if a type is a combination of object types. GraphQLBoolean
GraphQLEnumType
GraphQLFloat
Un-modi ers GraphQLID
GraphQLInputObjectType
function getNullableType GraphQLInt
Strips any non-null wrappers from a type.
GraphQLInterfaceType
GraphQLList
function getNamedType
Strips any non-null or list wrappers from a type. GraphQLNonNull
GraphQLObjectType
GraphQLScalarType
Scalars GraphQLSchema
GraphQLString
var GraphQLInt GraphQLUnionType
A scalar type representing integers. isAbstractType
isCompositeType
var GraphQLFloat isInputType
A scalar type representing oats.
isLeafType
isOutputType
var GraphQLString
A scalar type representing strings.
graphql/utilities
var GraphQLBoolean
A scalar type representing booleans. astFromValue
buildASTSchema
var GraphQLID buildClientSchema
A scalar type representing IDs. buildSchema
introspectionQuery
isValidJSValue
isValidLiteralValue
Schema printIntrospectionSchema
printSchema
typeFromAST
TypeInfo
GraphQLSchema
graphql/validation
class GraphQLSchema { speci edRules
constructor(config: GraphQLSchemaConfig) validate
}
type GraphQLSchemaConfig = {
query: GraphQLObjectType;
mutation?: ?GraphQLObjectType;
}
[Link] 2/11
9/13/2020 graphql/type | API Reference
A Schema is created by supplying the root types of each type of operation, query and
mutation (optional). A schema de nition is then supplied to the validator and executor.
Example
var MyAppSchema = new GraphQLSchema({
query: MyAppQueryRootType
mutation: MyAppMutationRootType
});
De nitions
GraphQLScalarType
class GraphQLScalarType<InternalType> {
constructor(config: GraphQLScalarTypeConfig<InternalType>)
}
type GraphQLScalarTypeConfig<InternalType> = {
name: string;
description?: ?string;
serialize: (value: mixed) => ?InternalType;
parseValue?: (value: mixed) => ?InternalType;
parseLiteral?: (valueAST: Value) => ?InternalType;
}
The leaf values of any request and input values to arguments are Scalars (or Enums)
and are de ned with a name and a series of serialization functions used to ensure
validity.
Example
var OddType = new GraphQLScalarType({
name: 'Odd',
serialize: oddValue,
parseValue: oddValue,
parseLiteral(ast) {
if ([Link] === [Link]) {
return oddValue(parseInt([Link], 10));
}
return null;
}
});
function oddValue(value) {
return value % 2 === 1 ? value : null;
}
GraphQLObjectType
[Link] 3/11
9/13/2020 graphql/type | API Reference
class GraphQLObjectType {
constructor(config: GraphQLObjectTypeConfig)
}
type GraphQLObjectTypeConfig = {
name: string;
interfaces?: GraphQLInterfacesThunk | Array<GraphQLInterfaceType>;
fields: GraphQLFieldConfigMapThunk | GraphQLFieldConfigMap;
isTypeOf?: (value: any, info?: GraphQLResolveInfo) => boolean;
description?: ?string
}
type GraphQLInterfacesThunk = () => Array<GraphQLInterfaceType>;
type GraphQLFieldConfigMapThunk = () => GraphQLFieldConfigMap;
// See below about resolver functions.
type GraphQLFieldResolveFn = (
source?: any,
args?: {[argName: string]: any},
context?: any,
info?: GraphQLResolveInfo
) => any
type GraphQLResolveInfo = {
fieldName: string,
fieldNodes: Array<Field>,
returnType: GraphQLOutputType,
parentType: GraphQLCompositeType,
schema: GraphQLSchema,
fragments: { [fragmentName: string]: FragmentDefinition },
rootValue: any,
operation: OperationDefinition,
variableValues: { [variableName: string]: any },
}
type GraphQLFieldConfig = {
type: GraphQLOutputType;
args?: GraphQLFieldConfigArgumentMap;
resolve?: GraphQLFieldResolveFn;
deprecationReason?: string;
description?: ?string;
}
type GraphQLFieldConfigArgumentMap = {
[argName: string]: GraphQLArgumentConfig;
};
type GraphQLArgumentConfig = {
type: GraphQLInputType;
defaultValue?: any;
description?: ?string;
}
type GraphQLFieldConfigMap = {
[fieldName: string]: GraphQLFieldConfig;
};
Almost all of the GraphQL types you de ne will be object types. Object types have a
name, but most importantly describe their elds.
When two types need to refer to each other, or a type needs to refer to itself in a eld,
you can use a function expression (aka a closure or a thunk) to supply the elds lazily.
[Link] 4/11
9/13/2020 graphql/type | API Reference
Note that resolver functions are provided the source object as the rst parameter.
However, if a resolver function is not provided, then the default resolver is used, which
looks for a method on source of the same name as the eld. If found, the method is
called with (args, context, info) . Since it is a method on source , that value can
always be referenced with this .
Examples
var AddressType = new GraphQLObjectType({
name: 'Address',
fields: {
street: { type: GraphQLString },
number: { type: GraphQLInt },
formatted: {
type: GraphQLString,
resolve(obj) {
return [Link] + ' ' + [Link]
}
}
}
});
var PersonType = new GraphQLObjectType({
name: 'Person',
fields: () => ({
name: { type: GraphQLString },
bestFriend: { type: PersonType },
})
});
GraphQLInterfaceType
class GraphQLInterfaceType {
constructor(config: GraphQLInterfaceTypeConfig)
}
type GraphQLInterfaceTypeConfig = {
name: string,
fields: GraphQLFieldConfigMapThunk | GraphQLFieldConfigMap,
resolveType?: (value: any, info?: GraphQLResolveInfo) => ?GraphQLObjectType,
description?: ?string
};
When a eld can return one of a heterogeneous set of types, a Interface type is used
to describe what types are possible, what elds are in common across all types, as
well as a function to determine which type is actually used when the eld is resolved.
Example
var EntityType = new GraphQLInterfaceType({
name: 'Entity',
fields: {
name: { type: GraphQLString }
}
});
[Link] 5/11
9/13/2020 graphql/type | API Reference
GraphQLUnionType
class GraphQLUnionType {
constructor(config: GraphQLUnionTypeConfig)
}
type GraphQLUnionTypeConfig = {
name: string,
types: GraphQLObjectsThunk | Array<GraphQLObjectType>,
resolveType?: (value: any, info?: GraphQLResolveInfo) => ?GraphQLObjectType;
description?: ?string;
};
type GraphQLObjectsThunk = () => Array<GraphQLObjectType>;
When a eld 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 eld is resolved.
Example
var PetType = new GraphQLUnionType({
name: 'Pet',
types: [ DogType, CatType ],
resolveType(value) {
if (value instanceof Dog) {
return DogType;
}
if (value instanceof Cat) {
return CatType;
}
}
});
GraphQLEnumType
class GraphQLEnumType {
constructor(config: GraphQLEnumTypeConfig)
}
type GraphQLEnumTypeConfig = {
name: string;
values: GraphQLEnumValueConfigMap;
description?: ?string;
}
type GraphQLEnumValueConfigMap = {
[valueName: string]: GraphQLEnumValueConfig;
};
type GraphQLEnumValueConfig = {
value?: any;
deprecationReason?: string;
description?: ?string;
}
[Link] 6/11
9/13/2020 graphql/type | API Reference
type GraphQLEnumValueDefinition = {
name: string;
value?: any;
deprecationReason?: string;
description?: ?string;
}
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.
Note: If a value is not provided in a de nition, the name of the enum value will be used
as its internal value.
Example
var RGBType = new GraphQLEnumType({
name: 'RGB',
values: {
RED: { value: 0 },
GREEN: { value: 1 },
BLUE: { value: 2 }
}
});
GraphQLInputObjectType
class GraphQLInputObjectType {
constructor(config: GraphQLInputObjectConfig)
}
type GraphQLInputObjectConfig = {
name: string;
fields: GraphQLInputObjectConfigFieldMapThunk | GraphQLInputObjectConfigFieldMap;
description?: ?string;
}
type GraphQLInputObjectConfigFieldMapThunk = () => GraphQLInputObjectConfigFieldMap;
type GraphQLInputObjectFieldConfig = {
type: GraphQLInputType;
defaultValue?: any;
description?: ?string;
}
type GraphQLInputObjectConfigFieldMap = {
[fieldName: string]: GraphQLInputObjectFieldConfig;
};
type GraphQLInputObjectField = {
name: string;
type: GraphQLInputType;
defaultValue?: any;
description?: ?string;
}
type GraphQLInputObjectFieldMap = {
[Link] 7/11
9/13/2020 graphql/type | API Reference
[fieldName: string]: GraphQLInputObjectField;
};
An input object de nes a structured collection of elds which may be supplied to a
eld argument.
Using NonNull will ensure that a value must be provided by the query
Example
var GeoPoint = new GraphQLInputObjectType({
name: 'GeoPoint',
fields: {
lat: { type: new GraphQLNonNull(GraphQLFloat) },
lon: { type: new GraphQLNonNull(GraphQLFloat) },
alt: { type: GraphQLFloat, defaultValue: 0 },
}
});
GraphQLList
class GraphQLList {
constructor(type: GraphQLType)
}
A list is a kind of type marker, a wrapping type which points to another type. Lists are
often created within the context of de ning the elds of an object type.
Example
var PersonType = new GraphQLObjectType({
name: 'Person',
fields: () => ({
parents: { type: new GraphQLList(PersonType) },
children: { type: new GraphQLList(PersonType) },
})
});
GraphQLNonNull
class GraphQLNonNull {
constructor(type: GraphQLType)
}
A non-null is a kind of type marker, 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 elds which you can make a strong
guarantee on non-nullability, for example usually the id eld of a database row will
never be null.
[Link] 8/11
9/13/2020 graphql/type | API Reference
Example
var RowType = new GraphQLObjectType({
name: 'Row',
fields: () => ({
id: { type: new GraphQLNonNull(String) },
})
});
Predicates
isInputType
function isInputType(type: ?GraphQLType): boolean
These types may be used as input types for arguments and directives.
isOutputType
function isOutputType(type: ?GraphQLType): boolean
These types may be used as output types as the result of elds
isLeafType
function isLeafType(type: ?GraphQLType): boolean
These types may describe types which may be leaf values
isCompositeType
function isCompositeType(type: ?GraphQLType): boolean
These types may describe the parent context of a selection set
isAbstractType
function isAbstractType(type: ?GraphQLType): boolean
These types may describe a combination of object types
[Link] 9/11
9/13/2020 graphql/type | API Reference
Un-modi ers
getNullableType
function getNullableType(type: ?GraphQLType): ?GraphQLNullableType
If a given type is non-nullable, this strips the non-nullability and returns the underlying
type.
getNamedType
function getNamedType(type: ?GraphQLType): ?GraphQLNamedType
If a given type is non-nullable or a list, this repeated strips the non-nullability and list
wrappers and returns the underlying type.
Scalars
GraphQLInt
var GraphQLInt: GraphQLScalarType;
A GraphQLScalarType that represents an int.
GraphQLFloat
var GraphQLFloat: GraphQLScalarType;
A GraphQLScalarType that represents a oat.
GraphQLString
var GraphQLString: GraphQLScalarType;
A GraphQLScalarType that represents a string.
GraphQLBoolean
var GraphQLBoolean: GraphQLScalarType;
[Link] 10/11
9/13/2020 graphql/type | API Reference
A GraphQLScalarType that represents a boolean.
GraphQLID
var GraphQLID: GraphQLScalarType;
A GraphQLScalarType that represents an ID.
Continue Reading →
graphql/utilities
Learn Code Community More
Introduction Servers Upcoming Events GraphQL Speci cation
Query Language Clients Stack Over ow GraphQL Foundation
Type System Tools Facebook Group GraphQL GitHub
Execution Twitter Edit this page ✎
Best Practices
Copyright © 2020 The GraphQL Foundation. All rights reserved. The Linux Foundation has registered trademarks and uses
trademarks. For a list of trademarks of The Linux Foundation, please see our Trademark Usage page. Linux is a registered
trademark of Linus Torvalds. Privacy Policy and Terms of Use.
[Link] 11/11