angel_graphql 1.0.0

Logo


Pub Pub

A complete implementation of the official GraphQL specification - these are the Angel framework-specific bindings.

The goal of this project is to provide to server-side users of Dart an alternative to REST API's. package:angel_graphql, which, when combined with the allows server-side Dart users to build backends with GraphQL and virtually any database imaginable.

Installation #

To install package:angel_graphql, add the following to your pubspec.yaml:

dependencies:
    angel_framework: ^2.0.0-alpha
    angel_graphql: ^1.0.0-alpha

Usage #

Using this package is very similar to GraphQL.js - you define a schema, and then mount graphQLHttp in your router to start serving. This implementation supports GraphQL features like introspection, so you can play around with graphiql as well!

Firstly, define your schema. A GraphQL schema contains an object type that defines all querying operations that can be applied to the backend.

A GraphQL schema may also have a mutation object type, which defines operations that change the backend's state, and optionally a subscription type, which defines real-time interactions (coming soon!).

You can use the convertDartType helper to wrap your existing Model/PODO classes, and make GraphQL aware of them without duplicated effort.

import 'package:angel_framework/angel_framework.dart';
import 'package:angel_graphql/angel_graphql.dart';
import 'package:graphql_schema/graphql_schema.dart';
import 'package:graphql_server/graphql_server.dart';
import 'package:graphql_server/mirrors.dart';

Future configureServer(Angel app) async {
    var queryType = objectType(
        'Query',
        description: 'A simple API that manages your to-do list.',
        fields: [
            field(
                'todos',
                listOf(convertDartType(Todo).nonNullable()),
                resolve: resolveViaServiceIndex(todoService),
            ),
            field(
                'todo',
                convertDartType(Todo),
                resolve: resolveViaServiceRead(todoService),
                inputs: [
                    new GraphQLFieldInput('id', graphQLId.nonNullable()),
                ],
            ),
        ],
    );

    var mutationType = objectType(
        'Mutation',
        description: 'Modify the to-do list.',
        fields: [
            field(
                'create',
                graphQLString,
            ),
        ],
    );

    var schema = graphQLSchema(
        queryType: queryType,
        mutationType: mutationType,
    );
}

After you've created your GraphQLSchema, you just need to wrap in a call to graphQLHttp, a request handler that responds to GraphQL.

In development, it's also highly recommended to mount the graphiQL handler, which serves GraphQL's official visual interface, for easy querying and feedback.

app.all('/graphql', graphQLHttp(new GraphQL(schema)));
app.get('/graphiql', graphiQL());

All that's left now is just to start the server!

var server = await http.startServer('127.0.0.1', 3000);
var uri =
    new Uri(scheme: 'http', host: server.address.address, port: server.port);
var graphiqlUri = uri.replace(path: 'graphiql');
print('Listening at $uri');
print('Access graphiql at $graphiqlUri');

Visit your /graphiql endpoint, and you'll see the graphiql UI, ready-to-go!

Graphiql screenshot

Now you're ready to build a GraphQL API!

Subscriptions #

Example: https://github.com/angel-dart/graphql/blob/master/angel_graphql/example/subscription.dart

In GraphQL, as of the June 2018 spec, clients can subscribe to streams of events from the server. In your schema, all you need to do is 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(
  // ...
  subscriptionType: objectType(
    'Subscription',
    fields: [
      field('postAdded', postType, resolve: (_, __) => postAdded),
    ],
  ),
);

By default, graphQLHttp has no support for subscriptions, because regular HTTP requests are stateless, and are not ideal for continuous data pushing. You can add your own handler:

graphQLHttp(graphQL, onSubscription: (req, res, stream) {
  // Do something with the stream here. It's up to you.
});

There is, however, graphQLWS, which implements Apollo's subscriptions-transport-ws protocol:

app.get('/subscriptions', graphQLWS(GraphQL(schema)));

You can then use existing JavaScript clients to handle subscriptions.

The graphiQL handler also supports using subscriptions. In the following snippet, the necessary scripts will be added to the rendered page, so that the subscriptions-transport-ws client can be used by GraphiQL:

app.get('/graphiql',
    graphiQL(subscriptionsEndpoint: 'ws://localhost:3000/subscriptions'));

NOTE: Apollo's spec for the aforementioned protocol is very far outdated, and completely inaccurate, See this issue for more: https://github.com/apollographql/subscriptions-transport-ws/issues/551

Using Services #

What would Angel be without services? For those unfamiliar - in Angel, Service is a base class that implements CRUD functionality, and serves as the database interface within an Angel application. They are well-suited for NoSQL or other databases without a schema (they can be used with SQL, but that's not their primary focus).

package:angel_graphql has functionality to resolve fields by interacting with services.

Consider our previous example, and note the calls to resolveViaServiceIndex and resolveViaServiceRead:

var queryType = objectType(
    'Query',
    description: 'A simple API that manages your to-do list.',
    fields: [
      field(
        'todos',
        listOf(convertDartType(Todo).nonNullable()),
        resolve: resolveViaServiceIndex(todoService),
      ),
      field(
        'todo',
        convertDartType(Todo),
        resolve: resolveViaServiceRead(todoService),
        inputs: [
          new GraphQLFieldInput('id', graphQLId.nonNullable()),
        ],
      ),
    ],
  );

In all, there are:

  • resolveViaServiceIndex
  • resolveViaServiceFindOne
  • resolveViaServiceRead
  • resolveViaServiceCreate
  • resolveViaServiceModify
  • resolveViaServiceUpdate
  • resolveViaServiceRemove

As one might imagine, using these convenience helpers makes it much quicker to implement CRUD functionality in a GraphQL API.

Documentation #

Using package:graphql_generator, you can generate GraphQL schemas for concrete Dart types:

configureServer(Angel app) async {
  var schema = graphQLSchema(
    queryType: objectType('Query', fields: [
      field('todos', listOf(todoGraphQLType), resolve: (_, __) => ...)
    ]);
  );
}

@graphQLClass
class Todo {
  String text;

  @GraphQLDocumentation(description: 'Whether this item is complete.')
  bool isComplete;
}

For more documentation, see: https://pub.dartlang.org/packages/graphql_generator

Mirrors #

NOTE: Mirrors support is deprecated, and will not be updated further.

The convertDartType function can automatically read the documentation from a type like the following:

@GraphQLDocumentation(description: 'Any object with a .text (String) property.')
abstract class HasText {
  String get text;
}

@serializable
@GraphQLDocumentation(
    description: 'A task that might not be completed yet. **Yay! Markdown!**')
class Todo extends Model implements HasText {
  String text;

  @GraphQLDocumentation(deprecationReason: 'Use `completion_status` instead.')
  bool completed;

  CompletionStatus completionStatus;

  Todo({this.text, this.completed, this.completionStatus});
}

@GraphQLDocumentation(description: 'The completion status of a to-do item.')
enum CompletionStatus { COMPLETE, INCOMPLETE }

You can also manually provide documentation for parameters and endpoints, via a description parameter on almost all related functions.

See package:graphql_schema for more documentation.

1.0.0 #

  • Apply package:pedantic.

1.0.0-rc.0 #

  • Finish graphQLWS.

1.0.0-beta.1 #

  • Add graphQLWS handler, and support subscriptions.

1.0.0-beta #

  • Angel RC updates.

1.0.0-alpha #

  • First official release.

example/main.dart

// ignore_for_file: deprecated_member_use
import 'package:angel_framework/angel_framework.dart';
import 'package:angel_framework/http.dart';
import 'package:angel_graphql/angel_graphql.dart';
import 'package:angel_serialize/angel_serialize.dart';
import 'package:graphql_schema/graphql_schema.dart';
import 'package:graphql_server/graphql_server.dart';
import 'package:graphql_server/mirrors.dart';
import 'package:logging/logging.dart';

main() async {
  var logger = Logger('angel_graphql');
  var app = Angel(
      logger: logger
        ..onRecord.listen((rec) {
          print(rec);
          if (rec.error != null) print(rec.error);
          if (rec.stackTrace != null) print(rec.stackTrace);
        }));
  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(convertDartType(Todo).nonNullable()),
        resolve: resolveViaServiceIndex(todoService),
      ),
      field(
        'todo',
        convertDartType(Todo),
        resolve: resolveViaServiceRead(todoService),
        inputs: [
          GraphQLFieldInput('id', graphQLId.nonNullable()),
        ],
      ),
    ],
  );

  var mutationType = objectType(
    'Mutation',
    description: 'Modify the to-do list.',
    fields: [
      field(
        'create',
        graphQLString,
      ),
    ],
  );

  var schema = graphQLSchema(
    queryType: queryType,
    mutationType: mutationType,
  );

  app.all('/graphql', graphQLHttp(GraphQL(schema)));
  app.get('/graphiql', graphiQL());

  await todoService
      .create({'text': 'Clean your room!', 'completion_status': 'COMPLETE'});
  await todoService.create(
      {'text': 'Take out the trash', 'completion_status': 'INCOMPLETE'});
  await todoService.create({
    'text': 'Become a billionaire at the age of 5',
    'completion_status': 'INCOMPLETE'
  });

  var server = await http.startServer('127.0.0.1', 3000);
  var uri =
      Uri(scheme: 'http', host: server.address.address, port: server.port);
  var graphiqlUri = uri.replace(path: 'graphiql');
  print('Listening at $uri');
  print('Access graphiql at $graphiqlUri');
}

@GraphQLDocumentation(description: 'Any object with a .text (String) property.')
abstract class HasText {
  String get text;
}

@serializable
@GraphQLDocumentation(
    description: 'A task that might not be completed yet. **Yay! Markdown!**')
class Todo extends Model implements HasText {
  String text;

  @GraphQLDocumentation(deprecationReason: 'Use `completion_status` instead.')
  bool completed;

  CompletionStatus completionStatus;

  Todo({this.text, this.completed, this.completionStatus});
}

@GraphQLDocumentation(description: 'The completion status of a to-do item.')
enum CompletionStatus { COMPLETE, INCOMPLETE }

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  angel_graphql: ^1.0.0

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:angel_graphql/angel_graphql.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
58
Health:
Code health derived from static analysis. [more]
99
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
79
Learn more about scoring.

We analyzed this package on Aug 22, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.4.0
  • pana: 0.12.19

Platforms

Detected platforms: Flutter, other

Primary library: package:angel_graphql/angel_graphql.dart with components: io.

Health suggestions

Fix lib/src/graphql_ws.dart. (-1 points)

Analysis of lib/src/graphql_ws.dart reported 2 hints:

line 26 col 13: DO use curly braces for all flow control structures.

line 28 col 13: DO use curly braces for all flow control structures.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0-dev <3.0.0
angel_file_service ^2.0.0 2.0.1
angel_framework ^2.0.0-alpha 2.0.4+1
angel_validate ^2.0.0-alpha 2.0.1+1
angel_websocket ^2.0.0 2.0.3
graphql_parser ^1.0.0 1.1.3
graphql_schema ^1.0.0 1.0.4
graphql_server ^1.0.0-beta 1.0.1
http_parser ^3.0.0 3.1.3
web_socket_channel ^1.0.0 1.0.15
Transitive dependencies
angel_auth 2.1.5+1
angel_client 2.0.2
angel_container 1.0.4
angel_http_exception 1.1.0
angel_model 1.0.3
angel_route 3.0.6
async 2.3.0
charcode 1.1.2
code_buffer 1.0.1
collection 1.14.12
combinator 1.1.0
convert 2.1.1
crypto 2.1.2
dart2_constant 1.0.2+dart2
http 0.12.0+2
http2 1.0.0
http_server 0.9.8+3
intl 0.15.8
json_god 2.0.0-beta+3
matcher 0.12.5
merge_map 1.0.2
meta 1.1.7
mime 0.9.6+3
mock_request 1.0.6
path 1.6.4
pool 1.4.0
quiver 2.0.5
quiver_hashcode 2.0.0
recase 2.0.1
source_span 1.5.5
stack_trace 1.9.3
stream_channel 2.0.0
string_scanner 1.0.5
term_glyph 1.1.0
tuple 1.0.2
typed_data 1.1.6
uuid 2.0.2
Dev dependencies
angel_serialize ^2.0.0 2.2.3+2
file ^5.0.0 5.0.8+1
logging ^0.11.0 0.11.3+2
pedantic ^1.0.0 1.8.0+1