GraphQL brings many benefits, both to the client: devices will need less requests, and therefore reduce data usage. And to the programer: requests are arguable, they have the same structure as the request.
This project combines the benefits of GraphQL with the benefits of Streams in Dart to deliver a high performance client.
The project took inspiration from the Apollo GraphQL client, great work guys!
First depend on the library by adding this to your packages pubspec.yaml:
dependencies:
graphql_flutter: ^1.0.0-betaNow inside your Dart code you can import it.
import 'package:graphql_flutter/graphql_flutter.dart';Here is a guide to fix most of the breaking changes introduced in 1.x.x.
Some class names have been renamed:
- Renamed
ClienttoGraphQLClient - Renamed
GraphqlProvidertoGraphQLProvider - Renamed
GraphqlConsumertoGraphQLConsumer - Renamed
GQLErrortoGraphQLError
We changed the way the client handles requests, it now uses a Link to execute queries rather then depend on the http package. We've currently only implemented the HttpLink, just drop it in like so:
void main() {
+ HttpLink link = HttpLink(
+ uri: 'https://api.github.com/graphql',
+ headers: <String, String>{
+ 'Authorization': 'Bearer <YOUR_PERSONAL_ACCESS_TOKEN>',
+ },
+ );
- ValueNotifier<Client> client = ValueNotifier(
+ ValueNotifier<GraphQLClient> client = ValueNotifier(
- Client(
- endPoint: 'https://api.github.com/graphql',
+ GraphQLClient(
cache: InMemoryCache(),
- apiToken: '<YOUR_GITHUB_PERSONAL_ACCESS_TOKEN>',
+ link: link,
),
);
}We have made a load of changes how queries and mutations work under the hood. To allow for these changes we had to make some small changes to the API of the Query and Mutation widgets.
Query(
- readRepositories,
+ options: QueryOptions(
+ document: readRepositories,
variables: {
'nRepositories': 50,
},
pollInterval: 10,
+ ),
- builder: ({
- bool loading,
- var data,
- String error,
- }) {
+ builder: (QueryResult result, { VoidCallback refetch }) {
- if (error != '') {
- return Text(error);
+ if (result.errors != null) {
+ return Text(result.errors.toString());
}
- if (loading) {
+ if (result.loading) {
return Text('Loading');
}
- List repositories = data['viewer']['repositories']['nodes'];
+ List repositories = result.data['viewer']['repositories']['nodes'];
return ListView.builder(
itemCount: repositories.length,
itemBuilder: (context, index) {
final repository = repositories[index];
return Text(repository['name']);
});
},
);Mutation(
- addStar,
+ options: MutationOptions(
+ document: addStar,
+ ),
builder: (
- runMutation, {
- bool loading,
- var data,
- String error,
+ RunMutation runMutation,
+ QueryResult result,
- }) {
+ ) {
return FloatingActionButton(
onPressed: () => runMutation({
'starrableId': <A_STARTABLE_REPOSITORY_ID>,
}),
tooltip: 'Star',
child: Icon(Icons.star),
);
},
);That's it! You should now be able to use the latest version of our library.
To use the client it first needs to be initialized with an link and cache. For this example we will be using an HttpLink as our link and InMemoryCache as our cache. If your endpoint requires authentication you can concatenate the AuthLink, it resolves the credentials using a future, so you can authenticate asynchronously.
For this example we will use the public GitHub API.
...
import 'package:graphql_flutter/graphql_flutter.dart';
void main() {
final HttpLink httpLink = HttpLink(
uri: 'https://api.github.com/graphql',
);
final AuthLink authLink = AuthLink(
getToken: () => async 'Bearer <YOUR_PERSONAL_ACCESS_TOKEN>',
);
final Link link = authLink.concat(httpLink);
ValueNotifier<GraphQLClient> client = ValueNotifier(
GraphQLClient(
cache: InMemoryCache(),
link: link,
),
);
...
}
...In order to use the client, you Query and Mutation widgets to be wrapped with the GraphQLProvider widget.
We recommend wrapping your
MaterialAppwith theGraphQLProviderwidget.
...
return GraphQLProvider(
client: client,
child: MaterialApp(
title: 'Flutter Demo',
...
),
);
...The in-memory cache can automatically be saved to and restored from offline storage. Setting it up is as easy as wrapping your app with the CacheProvider widget.
It is required to place the
CacheProviderwidget is inside theGraphQLProviderwidget, becauseGraphQLProvidermakes client available through the build context.
...
class MyApp extends StatelessWidget {
@override
Widget build(BuildContext context) {
return GraphQLProvider(
client: client,
child: CacheProvider(
child: MaterialApp(
title: 'Flutter Demo',
...
),
),
);
}
}
...To enable apollo-like normalization, use a NormalizedInMemoryCache or OptimisticCache:
ValueNotifier<GraphQLClient> client = ValueNotifier(
GraphQLClient(
cache: NormalizedInMemoryCache(
dataIdFromObject: typenameDataIdFromObject,
),
link: link,
),
);dataIdFromObject is required and has no defaults. Our implementation is similar to apollo's, requiring a function to return a universally unique string or null. The predefined typenameDataIdFromObject we provide is similar to apollo's default:
String typenameDataIdFromObject(Object object) {
if (object is Map<String, Object> &&
object.containsKey('__typename') &&
object.containsKey('id')) {
return "${object['__typename']}/${object['id']}";
}
return null;
}However note that graphql-flutter does not inject __typename into operations the way apollo does, so if you aren't careful to request them in your query, this normalization scheme is not possible.
Unlike apollo, we don't have a real client side document parser and resolver, so operations leveraging normalization can have additional fields not specified in the query. There are a couple ideas for constraining this (leveraging json_serializable, or just implementing the resolver), but for now, the normalized cache uses a LazyMap, which wraps underlying data with a lazy denormalizer to allow for cyclical references. It has the same API as a normal HashMap, but is currently a bit hard to debug with, as a descriptive debug representation is currently unavailable.
The OptimisticCache allows for optimistic mutations by passing an optimisticResult to RunMutation. It will then call update(Cache cache, QueryResult result) twice (once eagerly with optimisticResult), and rebroadcast all queries with the optimistic cache. You can tell which entities in the cache are optimistic through the .isOptimistic flag on LazyMap, though note that this is only the case for optimistic entities and not their containing operations/maps.
QueryResults also have an optimistic flag, but I would recommend looking at the data itself, as many situations make it unusable (such as toggling mutations like in the example below). Mutation usage examples
Creating a query is as simple as creating a multiline string:
String readRepositories = """
query ReadRepositories(\$nRepositories) {
viewer {
repositories(last: \$nRepositories) {
nodes {
id
name
viewerHasStarred
}
}
}
}
""";In your widget:
// ...
Query(
options: QueryOptions(
document: readRepositories, // this is the query string you just created
variables: {
'nRepositories': 50,
},
pollInterval: 10,
),
// Just like in apollo refetch() could be used to manually trigger a refetch
builder: (QueryResult result, { VoidCallback refetch }) {
if (result.errors != null) {
return Text(result.errors.toString());
}
if (result.loading) {
return Text('Loading');
}
// it can be either Map or List
List repositories = result.data['viewer']['repositories']['nodes'];
return ListView.builder(
itemCount: repositories.length,
itemBuilder: (context, index) {
final repository = repositories[index];
return Text(repository['name']);
});
},
);
// ...Again first create a mutation string:
String addStar = """
mutation AddStar(\$starrableId: ID!) {
addStar(input: {starrableId: \$starrableId}) {
starrable {
viewerHasStarred
}
}
}
""";The syntax for mutations is fairly similar to that of a query. The only diffence is that the first argument of the builder function is a mutation function. Just call it to trigger the mutations (Yeah we deliberately stole this from react-apollo.)
...
Mutation(
options: MutationOptions(
document: addStar, // this is the mutation string you just created
),
builder: (
RunMutation runMutation,
QueryResult result,
) {
return FloatingActionButton(
onPressed: () => runMutation({
'starrableId': <A_STARTABLE_REPOSITORY_ID>,
}),
tooltip: 'Star',
child: Icon(Icons.star),
);
},
// you can update the cache based on results
update: (Cache cache, QueryResult result) {
return cache;
},
// or do something with the result.data on completion
onCompleted: (dynamic resultData) {
print(resultData);
},
);
...If you're using an OptimisticCache, you can provide an optimisticResult:
...
FlutterWidget(
onTap: () {
toggleStar(
{ 'starrableId': repository['id'] },
optimisticResult: {
'action': {
'starrable': {'viewerHasStarred': !starred}
}
},
);
},
)
...With a bit more context (taken from the complete mutation example StarrableRepository):
// bool get starred => repository['viewerHasStarred'] as bool;
// bool get optimistic => (repository as LazyMap).isOptimistic;
Mutation(
options: MutationOptions(
document: starred ? mutations.removeStar : mutations.addStar,
),
builder: (RunMutation toggleStar, QueryResult result) {
return ListTile(
leading: starred
? const Icon(
Icons.star,
color: Colors.amber,
)
: const Icon(Icons.star_border),
trailing: result.loading || optimistic
? const CircularProgressIndicator()
: null,
title: Text(repository['name'] as String),
onTap: () {
toggleStar(
{ 'starrableId': repository['id'] },
optimisticResult: {
'action': {
'starrable': {'viewerHasStarred': !starred}
}
},
);
},
);
},
// will be called for both optimistic and final results
update: (Cache cache, QueryResult result) {
if (result.hasErrors) {
print(['optimistic', result.errors]);
} else {
final Map<String, Object> updated =
Map<String, Object>.from(repository)
..addAll(extractRepositoryData(result.data));
cache.write(typenameDataIdFromObject(updated), updated);
}
},
// will only be called for final result
onCompleted: (dynamic resultData) {
showDialog<AlertDialog>(
context: context,
builder: (BuildContext context) {
return AlertDialog(
title: Text(
extractRepositoryData(resultData)['viewerHasStarred'] as bool
? 'Thanks for your star!'
: 'Sorry you changed your mind!',
),
actions: <Widget>[
SimpleDialogOption(
child: const Text('Dismiss'),
onPressed: () {
Navigator.of(context).pop();
},
)
],
);
},
);
},
);The syntax for subscriptions is again similar to a query, however, this utilizes WebSockets and dart Streams to provide real-time updates from a server.
Before subscriptions can be performed a global instance of socketClient needs to be initialized.
We are working on moving this into the same
GraphQLProviderstructure as the http client. Therefore this api might change in the near future.
socketClient = await SocketClient.connect('ws://coolserver.com/graphql');Once the socketClient has been initialized it can be used by the Subscription Widget
class _MyHomePageState extends State<MyHomePage> {
@override
Widget build(BuildContext context) {
return Scaffold(
body: Center(
child: Subscription(
operationName,
query,
variables: variables,
builder: ({
bool loading,
dynamic payload,
dynamic error,
}) {
if (payload != null) {
return Text(payload['requestSubscription']['requestData']);
} else {
return Text('Data not found');
}
}
),
)
);
}
}You can always access the client directly from the GraphQLProvider but to make it even easier you can also use the GraphQLConsumer widget.
...
return GraphQLConsumer(
builder: (GraphQLClient client) {
// do something with the client
return Container(
child: Text('Hello world'),
);
},
);
...We support GraphQL Upload spec as proposed at https://github.com/jaydenseric/graphql-multipart-request-spec
mutation($files: [Upload!]!) {
multipleUpload(files: $files) {
id
filename
mimetype
path
}
}
import 'dart:io' show File;
// ...
String filePath = '/aboslute/path/to/file.ext';
final QueryResult r = await graphQLClientClient.mutate(
MutationOptions(
document: uploadMutation,
variables: {
'files': [File(filePath)],
},
)
);This is currently our roadmap, please feel free to request additions/changes.
| Feature | Progress |
|---|---|
| Queries | ✅ |
| Mutations | ✅ |
| Subscriptions | ✅ |
| Query polling | ✅ |
| In memory cache | ✅ |
| Offline cache sync | ✅ |
| GraphQL pload | ✅ |
| Optimistic results | ✅ |
| Client state management | 🔜 |
| Modularity | 🔜 |
Feel free to open a PR with any suggestions! We'll be actively working on the library ourselves.
This package was originally created and published by the engineers at Zino App BV. Since then the community has helped to make it even more useful for even more developers.
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind are welcome!