angel3_graphql 10.0.0
angel3_graphql: ^10.0.0 copied to clipboard
The fastest and easiest way to get a GraphQL backend in Dart, using Angel3.
Angel3 Graphql #

GraphQL for the Angel3 framework: request handlers that serve a GraphQL API over HTTP and WebSockets, GraphiQL, and resolvers backed by Angel services. It builds on package:graphql_server2, which implements the GraphQL specification, so you can build a GraphQL backend with Dart and virtually any database.
Installation #
Add the following to your pubspec.yaml:
dependencies:
angel3_framework: ^10.0.0
angel3_graphql: ^10.0.0
angel3_serialize: ^10.0.0
graphql_schema2: ^8.0.0
graphql_server2: ^9.0.0
dev_dependencies:
angel3_serialize_generator: ^10.0.0
build_runner: ^2.7.0
graphql_generator2: ^8.0.0
The generators are needed only to generate GraphQL types from your models, as below.
Usage #
Using this package is much like GraphQL.js: define a schema, and mount graphQLHttp in your router to serve it. Introspection is supported, so you can explore the API with GraphiQL.
A schema has a query type, of the operations that read data, and optionally a mutation type, of those that change it, and a subscription type, of real-time events (see Subscriptions).
Here, todoGraphQLType is generated from the TodoEntity model by package:graphql_generator2 (see Generating Types), so GraphQL knows the model without duplicated effort. Run dart run build_runner build to generate it:
import 'package:angel3_framework/angel3_framework.dart';
import 'package:angel3_framework/http.dart';
import 'package:angel3_graphql/angel3_graphql.dart';
import 'package:angel3_serialize/angel3_serialize.dart';
import 'package:graphql_schema2/graphql_schema2.dart';
import 'package:graphql_server2/graphql_server2.dart';
part 'main.g.dart';
@serializable
@graphQLClass
abstract class TodoEntity extends Model {
String? get text;
@GraphQLDocumentation(description: 'Whether this item is complete.')
bool? get isComplete;
}
void main() async {
var app = Angel();
var http = AngelHttp(app);
var todoService = app.use('api/todos', MapService());
var queryType = objectType(
'Query',
description: 'A simple API that manages your to-do list.',
fields: [
field(
'todos',
listOf(todoGraphQLType.nonNullable()),
resolve: resolveViaServiceIndex(todoService),
),
field(
'todo',
todoGraphQLType,
resolve: resolveViaServiceRead(todoService),
inputs: [GraphQLFieldInput('id', graphQLId.nonNullable())],
),
],
);
var mutationType = objectType(
'Mutation',
description: 'Modify the to-do list.',
fields: [
field(
'createTodo',
todoGraphQLType,
inputs: [
GraphQLFieldInput('data', todoGraphQLType.coerceToInputObject()),
],
resolve: resolveViaServiceCreate(todoService),
),
],
);
var schema = graphQLSchema(queryType: queryType, mutationType: mutationType);
// Serve GraphQL, and GraphiQL to explore it in development.
app.all('/graphql', graphQLHttp(GraphQL(schema)));
app.get('/graphiql', graphiQL());
var server = await http.startServer('127.0.0.1', 3000);
print('Listening at http://${server.address.address}:${server.port}');
print('Access GraphiQL at http://${server.address.address}:${server.port}/graphiql');
}
Visit /graphiql, and you'll see the GraphiQL UI, ready to go:

Complete example: example/main.dart
Subscriptions #
Example: example/subscription.dart
Clients can subscribe to streams of events from the server. In your schema, return a Stream from a resolve callback, rather than a plain object:
var postAdded = postService.afterCreated
.asStream()
.map((e) => {'postAdded': e.result})
.asBroadcastStream();
var schema = graphQLSchema(
queryType: queryType,
subscriptionType: objectType(
'Subscription',
fields: [field('postAdded', postType, resolve: (_, _) => postAdded)],
),
);
HTTP requests are not suited to pushing data continuously, so graphQLHttp does not serve subscriptions unless you handle their streams yourself:
graphQLHttp(graphQL, onSubscription: (req, res, stream) {
// Do something with the stream here. It's up to you.
});
graphQLWS serves them over WebSockets, so you can use existing JavaScript clients:
app.get('/subscriptions', graphQLWS(GraphQL(schema)));
It speaks both WebSocket protocols for GraphQL, chosen by the subprotocol the client asks for:
graphql-transport-ws, of thegraphql-wslibrary, which current clients use, such as Apollo Client 3, urql and GraphiQL 2;graphql-ws, of Apollo's oldersubscriptions-transport-ws, also for a client that asks for none.
Queries and mutations can be sent over the socket too. To authenticate connections, check the payload of their connection_init:
app.get(
'/subscriptions',
graphQLWS(
GraphQL(schema),
onConnect: (req, payload) => payload?['token'] == 'secret',
),
);
A rejected connection is closed (with code 4403 for graphql-transport-ws). keepAliveInterval sets how often to send keep-alive messages, and connectionInitWaitTimeout how long to wait for a connection_init.
GraphiQL can run subscriptions too: give graphiQL the endpoint of graphQLWS, a path of the page's host or a ws:// or wss:// URL, and it subscribes over graphql-transport-ws:
app.get('/graphiql', graphiQL(subscriptionsEndpoint: '/subscriptions'));
The page loads GraphiQL 4 and React 18 from unpkg, pinned to exact versions and checked by their integrity hashes, so it needs internet access in the browser.
NOTE: Apollo's specification of the older protocol is out of date with what its client expects. See https://github.com/apollographql/subscriptions-transport-ws/issues/551.
WebSockets are served over HTTP/1.1.
Using Services #
In Angel, a Service implements CRUD operations, and is the database interface of an application. package:angel3_graphql resolves fields with services: in the example above, resolveViaServiceIndex, resolveViaServiceRead and resolveViaServiceCreate. In all, there are:
resolveViaServiceIndexresolveViaServiceFindOneresolveViaServiceRead(with anidargument)resolveViaServiceCreate(with adataargument)resolveViaServiceModify(withidanddata)resolveViaServiceUpdate(withidanddata)resolveViaServiceRemove(with anid)
Arguments are passed to the service as its query, with the request's context, and Providers.graphQL as the provider, so hooks can tell GraphQL requests apart.
File Uploads #
graphQLHttp serves file uploads by the GraphQL multipart request specification, which clients such as apollo-upload-client follow. Give an argument the Upload scalar, graphQLUpload; its value is the request's UploadedFile:
var mutationType = objectType(
'Mutation',
fields: [
field(
'upload',
graphQLString,
inputs: [GraphQLFieldInput('file', graphQLUpload.nonNullable())],
resolve: (_, args) async {
var file = args['file'] as UploadedFile;
var bytes = await file.data.fold<int>(0, (n, chunk) => n + chunk.length);
return '${file.filename}: $bytes bytes';
},
),
],
);
A client sends a multipart/form-data request of three kinds of parts: operations, the JSON of the request with null for each file; map, which tells for each file part the variables it goes in; and the files:
operations: {"query": "mutation($file: Upload!) { upload(file: $file) }", "variables": {"file": null}}
map: {"0": ["variables.file"]}
0: (the file)
A file can also go in a list, as variables.files.0, or a nested input object.
Generating Types #
package:graphql_generator2 generates a GraphQL type for each @graphQLClass model, as todoGraphQLType for TodoEntity above. With package:angel3_serialize_generator, dart run build_runner build generates both the Todo model and todoGraphQLType.
Its fields have resolvers, so a resolver can return Todo models, the maps of toJson(), or the records of a service:
field(
'todos',
listOf(todoGraphQLType),
resolve: (_, _) => [Todo(text: 'Clean your room!')],
);
Fields the serializer excludes, such as @SerializableField(exclude: true), are not part of the GraphQL type. You can also give descriptions to types, fields and arguments, with doc comments, @GraphQLDocumentation, or the description parameter of most helpers.
See package:graphql_generator2 and package:graphql_schema2 for more.
Migrating from 9.x #
convertDartType and the other mirrors helpers are removed from package:graphql_server2: generate types with package:graphql_generator2 instead, as above. See the change log for what changed in 10.0.0.