Skip to main content

angel3_graphql 10.0.0 copy "angel3_graphql: ^10.0.0" to clipboard
angel3_graphql: ^10.0.0 copied to clipboard

The fastest and easiest way to get a GraphQL backend in Dart, using Angel3.

Angel3 Graphql #

Logo

Pub Version (including pre-releases) Null Safety Gitter License melos

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:

GraphiQL screenshot

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 the graphql-ws library, which current clients use, such as Apollo Client 3, urql and GraphiQL 2;
  • graphql-ws, of Apollo's older subscriptions-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:

  • resolveViaServiceIndex
  • resolveViaServiceFindOne
  • resolveViaServiceRead (with an id argument)
  • resolveViaServiceCreate (with a data argument)
  • resolveViaServiceModify (with id and data)
  • resolveViaServiceUpdate (with id and data)
  • resolveViaServiceRemove (with an id)

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.