GraphQL

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';// ES6var{ GraphQLSchema }=require('graphql');// CommonJS

Overview #

Schema

Definitions

Predicates

Un-modifiers

Scalars

Schema #

GraphQLSchema #

classGraphQLSchema{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 =newGraphQLSchema({ query: MyAppQueryRootType mutation: MyAppMutationRootType });

Definitions #

GraphQLScalarType #

classGraphQLScalarType<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 =newGraphQLScalarType({ name:'Odd', serialize: oddValue, parseValue: oddValue,parseLiteral(ast){if(ast.kind === Kind.INT){returnoddValue(parseInt(ast.value,10));}returnnull;}});functionoddValue(value){return value %2===1? value :null;}

GraphQLObjectType #

classGraphQLObjectType{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 =newGraphQLObjectType({ name:'Address', fields:{ street:{ type: GraphQLString }, number:{ type: GraphQLInt }, formatted:{ type: GraphQLString,resolve(obj){return obj.number +' '+ obj.street }}}});var PersonType =newGraphQLObjectType({ name:'Person', fields:()=>({ name:{ type: GraphQLString }, bestFriend:{ type: PersonType },})});

GraphQLInterfaceType #

classGraphQLInterfaceType{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 =newGraphQLInterfaceType({ name:'Entity', fields:{ name:{ type: GraphQLString }}});

GraphQLUnionType #

classGraphQLUnionType{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 =newGraphQLUnionType({ name:'Pet', types:[ DogType, CatType ],resolveType(value){if(value instanceofDog){return DogType;}if(value instanceofCat){return CatType;}}});

GraphQLEnumType #

classGraphQLEnumType{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 =newGraphQLEnumType({ name:'RGB', values:{ RED:{ value:0}, GREEN:{ value:1}, BLUE:{ value:2}}});

GraphQLInputObjectType #

classGraphQLInputObjectType{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 =newGraphQLInputObjectType({ name:'GeoPoint', fields:{ lat:{ type:newGraphQLNonNull(GraphQLFloat)}, lon:{ type:newGraphQLNonNull(GraphQLFloat)}, alt:{ type: GraphQLFloat, defaultValue:0},}});

GraphQLList #

classGraphQLList{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 =newGraphQLObjectType({ name:'Person', fields:()=>({ parents:{ type:newGraphQLList(PersonType)}, children:{ type:newGraphQLList(PersonType)},})});

GraphQLNonNull #

classGraphQLNonNull{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 =newGraphQLObjectType({ name:'Row', fields:()=>({ id:{ type:newGraphQLNonNull(String)},})});

Predicates #

isInputType #

functionisInputType(type:?GraphQLType): boolean

These types may be used as input types for arguments and directives.

isOutputType #

functionisOutputType(type:?GraphQLType): boolean

These types may be used as output types as the result of fields

isLeafType #

functionisLeafType(type:?GraphQLType): boolean

These types may describe types which may be leaf values

isCompositeType #

functionisCompositeType(type:?GraphQLType): boolean

These types may describe the parent context of a selection set

isAbstractType #

functionisAbstractType(type:?GraphQLType): boolean

These types may describe a combination of object types

Un-modifiers #

getNullableType #

functiongetNullableType(type:?GraphQLType):?GraphQLNullableType

If a given type is non-nullable, this strips the non-nullability and returns the underlying type.

getNamedType #

functiongetNamedType(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