GraphQL LogoGraphQL

graphql/type

The graphql/type module is responsible for defining GraphQL types and schema. You can import either from the graphql/type module, or from the root graphql module. For example:

import { GraphQLSchema } from 'graphql'; // ES6
var { GraphQLSchema } = require('graphql'); // CommonJS

Overview#

Schema

Definitions

Predicates

Un-modifiers

Scalars

Schema#

GraphQLSchema#

class GraphQLSchema {
constructor(config: GraphQLSchemaConfig)
}
type GraphQLSchemaConfig = {
query: GraphQLObjectType;
mutation?: ?GraphQLObjectType;
}

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#

var MyAppSchema = new GraphQLSchema({
query: MyAppQueryRootType
mutation: MyAppMutationRootType
});

Definitions#

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 defined 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 (ast.kind === Kind.INT) {
return oddValue(parseInt(ast.value, 10));
}
return null;
}
});
function oddValue(value) {
return value % 2 === 1 ? value : null;
}

GraphQLObjectType#

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 define will be object types. Object types have a name, but most importantly describe their fields.

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.

Note that resolver functions are provided the source object as the first 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 field. 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 obj.number + ' ' + obj.street
}
}
}
});
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 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#

var EntityType = new GraphQLInterfaceType({
name: 'Entity',
fields: {
name: { type: GraphQLString }
}
});

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 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#

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;
}
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 definition, 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 = {
[fieldName: string]: GraphQLInputObjectField;
};

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#

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 defining the fields 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 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#

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 fields

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

Un-modifiers#

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 float.

GraphQLString#

var GraphQLString: GraphQLScalarType;

A GraphQLScalarType that represents a string.

GraphQLBoolean#

var GraphQLBoolean: GraphQLScalarType;

A GraphQLScalarType that represents a boolean.

GraphQLID#

var GraphQLID: GraphQLScalarType;

A GraphQLScalarType that represents an ID.

Continue Reading →graphql/utilities