git-subtree-dir: packages/graphql git-subtree-mainline:ac29392d7f
git-subtree-split:33e2f86ba7
4 KiB
graphql_schema
An implementation of GraphQL's type system in Dart. Supports any platform where Dart runs. The decisions made in the design of this library were done to make the experience as similar to the JavaScript reference implementation as possible, and to also correctly implement the official specification.
Contains functionality to build all GraphQL types:
String
Int
Float
Boolean
GraphQLObjectType
GraphQLUnionType
GraphQLEnumType
GraphQLInputObjectType
Date
- ISO-8601 Date string, deserializes to a DartDateTime
object
Of course, for a full description of GraphQL's type system, see the official specification: http://facebook.github.io/graphql/October2016/
Mostly analogous to graphql-js
; many names are verbatim:
https://graphql.org/graphql-js/type/
Usage
It's easy to define a schema with the helper functions:
final GraphQLSchema todoSchema = new GraphQLSchema(
query: objectType('Todo', [
field('text', graphQLString.nonNullable()),
field('created_at', graphQLDate)
]));
All GraphQL types are generic, in order to leverage Dart's strong typing support.
Serialization
GraphQL types can serialize
and deserialize
input data.
The exact implementation of this depends on the type.
var iso8601String = graphQLDate.serialize(new DateTime.now());
var date = graphQLDate.deserialize(iso8601String);
print(date.millisecondsSinceEpoch);
Validation
GraphQL types can validate
input data.
var validation = myType.validate('@root', {...});
if (validation.successful) {
doSomething(validation.value);
} else {
print(validation.errors);
}
Helpers
graphQLSchema
- Create aGraphQLSchema
objectType
- Create aGraphQLObjectType
with fieldsfield
- Create aGraphQLField
with a type/argument/resolverlistOf
- Create aGraphQLListType
with the providedinnerType
inputObjectType
- Creates aGraphQLInputObjectType
inputField
- Creates a field for aGraphQLInputObjectType
Types
All of the GraphQL scalar types are built in, as well as a Date
type:
graphQLString
graphQLId
graphQLBoolean
graphQLInt
graphQLFloat
graphQLDate
Non-Nullable Types
You can easily make a type non-nullable by calling its nonNullable
method.
List Types
Support for list types is also included. Use the listType
helper for convenience.
/// A non-nullable list of non-nullable integers
listOf(graphQLInt.nonNullable()).nonNullable();
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:graphql_schema
, use GraphQLFieldInput
:
final GraphQLObjectType queryType = objectType('AnimeQuery', fields: [
field('characters',
listOf(characterType.nonNullable()),
inputs: [
new GraphQLFieldInput('title', graphQLString.nonNullable())
]
),
]);
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:graphql_schema
includes this functionality in the resolve
property,
which is passed a context object and a Map<String, dynamic>
of arguments.
A hypothetical example of the above might be:
var field = field(
'characters',
graphQLString,
resolve: (_, args) async {
return await myDatabase.findCharacters(args['title']);
},
);