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 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.