graphql

More sophisticated GraphQL servers, such as those which persist queries, may wish to separate the validation and execution phases to a static time tooling step, and a server runtime step.

Accepts either an object with named arguments, or individual arguments:

schema: The GraphQL type system to use when validating and executing a query. source: A GraphQL language formatted string representing the requested operation. rootValue: The value provided as the first argument to resolver functions on the top level type (e.g. the query object type). contextValue: The context value is provided as an argument to resolver functions after field arguments. It is used to pass shared information useful at any point during executing this query, for example the currently logged in user and connections to databases or other services. variableValues: A mapping of variable name to runtime value to use for all variables defined in the requestString. operationName: The name of the operation to use if requestString contains multiple possible operations. Can be omitted if requestString contains only one operation. fieldResolver: A resolver function to use when one is not provided by the schema. If not provided, the default field resolver is used (which looks for a value or method on the source value with the field's name). typeResolver: A type resolver function to use when none is provided by the schema. If not provided, the default type resolver is used (which looks for a __typename field or alternatively calls the isTypeOf method).

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 ]),
})

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;
  }
});

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 },
  })
});

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 }
  }
});

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;
    }
  }
});

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.

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 },
  }
});

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) },
  })
})

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.

Validation runs synchronously, returning an array of encountered errors, or an empty array if no errors were encountered and the Schema is valid.

@internal —

@remarks — Use a unique identifier name for your extension, for example the name of your library or project. Do not use a shortened identifier as this increases the risk of conflicts. We recommend you add at most one extension field, an object which can contain all the values you need.

@remarks — Use a unique identifier name for your extension, for example the name of your library or project. Do not use a shortened identifier as this increases the risk of conflicts. We recommend you add at most one extension field, an object which can contain all the values you need.

@remarks — Use a unique identifier name for your extension, for example the name of your library or project. Do not use a shortened identifier as this increases the risk of conflicts. We recommend you add at most one extension field, an object which can contain all the values you need.

@remarks — Use a unique identifier name for your extension, for example the name of your library or project. Do not use a shortened identifier as this increases the risk of conflicts. We recommend you add at most one extension field, an object which can contain all the values you need.

@remarks — Use a unique identifier name for your extension, for example the name of your library or project. Do not use a shortened identifier as this increases the risk of conflicts. We recommend you add at most one extension field, an object which can contain all the values you need.

@remarks — Use a unique identifier name for your extension, for example the name of your library or project. Do not use a shortened identifier as this increases the risk of conflicts. We recommend you add at most one extension field, an object which can contain all the values you need.

We've provided these template arguments because this is an open type and you may find them useful.