Skip to main content

GraphQL Types

For a more thorough discussion about all the GraphQL types and their usage with Leto, please see the GraphQL Schema Types Documentation.

Scalar types​

All of the GraphQL scalar types (GraphQLScalarType) are built in:

  • graphQLString
  • graphQLId
  • graphQLBoolean
  • graphQLInt
  • graphQLFloat

As well other additional types, provided for types in Dart's standard library:

Additional scalar types​

  • graphQLDate
  • graphQLBigInt
  • graphQLTimestamp
  • graphQLUri

Composed Types​

  • GraphQLObjectType
  • GraphQLUnionType
  • GraphQLEnumType
  • GraphQLInputObjectType
  • GraphQLListType
  • GraphQLNonNullType

Helpers and Extensions​

These are helpers to create a GraphQL types within Dart. Most of them can be found in the /lib/src/gen.dart file.

  • objectType - Create a GraphQLObjectType with fields
  • field - Create a GraphQLField with a type/argument/resolver
  • inputObjectType - Creates a GraphQLInputObjectType
  • inputField - Creates a field for a GraphQLInputObjectType
  • listOf - Create a GraphQLListType with the provided innerType

Methods on GraphQLType​

  • list - Create a GraphQLListType from the type
  • nonNull - Create a GraphQLNonNullType from the type
  • nullable - Returns the inner type of GraphQLNonNullType or itself it it is nullable
  • field - Create a GraphQLField (extension method)
  • inputField - Create a field for a GraphQLInputObjectType (extension method)

The extensions on GraphQLType with the field and inputField methods are recommended over the global function to preserve the GraphQLType's generic type information.

Serialization and SerdeCtx​

GraphQL types can serialize and deserialize input data. The exact implementation of this depends on the type.

final serdeCtx = SerdeCtx();
final String iso8601String = graphQLDate.serialize(DateTime.now());
final DateTime date = graphQLDate.deserialize(serdeCtx, iso8601String);
print(date.millisecondsSinceEpoch);

Values passed through deserialize and serialize should round-trip.

SerdeCtx​

A Serialization and Deserialization Context (SerdeCtx) allows you to create types from serialized values. It registers Serializers for any type that can be used with generics.

Validation​

GraphQL types can validate input data. If the validation is successful, the GraphQLType.deserialize method should return an instance of the Dart type.

final validation = myType.validate('key', {...});

if (validation.successful) {
  doSomething(validation.value);
} else {
  print(validation.errors);
}

Non-Nullable Types​

You can easily make a type non-nullable by calling its nonNull method.

List Types​

Support for list types is also included. Use the list method from GraphQLType or the listOf helper function for convenience.

/// A non-nullable list of non-nullable integers
listOf(graphQLInt.nonNull()).nonNull();

Input values and parameters​

Take the following GraphQL query:

{
   anime {
     characters(title: "Hunter x Hunter") {
        name
        age
     }
   }
}

And subsequently, its schema:

type AnimeQuery {
  characters($title: String!): [Character!]
}

type Character {
  name: String
  age: Int
}

The field characters accepts a parameter, title. To reproduce this in package:leto_schema, use GraphQLFieldInput:

final GraphQLObjectType queryType = objectType(
  'AnimeQuery',
  fields: [
    field(
      'characters',
      listOf(characterType.nonNull()),
      inputs: [
        GraphQLFieldInput('title', graphQLString.nonNull()),
      ],
    ),
  ],
);

final GraphQLObjectType characterType = objectType(
  'Character',
  fields: [
    field('name', graphQLString),
    field('age', graphQLInt),
  ],
);

In the majority of cases where you use GraphQL, you will be delegate the actual fetching of data to a database object, or some asynchronous resolver function.

package:leto_schema includes this functionality in the resolve parameter, which is a function that receives the parent object and a Ctx with a Map<String, dynamic> of input arguments.

A hypothetical example of the above might be:

final field = field(
  'characters',
  graphQLString,
  resolve: (_, Ctx ctx) async {
    final Stream<String> stream = await myDatabase.findCharacters(ctx.args['title']);
    return stream;
  },
);