V4: Cache overhaul, gql_link integration, and more

.gitignore

@@ -112,6 +112,8 @@ unlinked_spec.ds
 **/ios/.generated/
 **/ios/Flutter/App.framework
 **/ios/Flutter/Flutter.framework
+**/ios/Flutter/Flutter.podspec
+**/ios/Flutter/.last_build_id
 **/ios/Flutter/Flutter/Flutter.podspec
 **/ios/Flutter/Generated.xcconfig
 **/ios/Flutter/app.flx

changelog-v3-v4.md

@@ -0,0 +1,142 @@
+# Migrating from v3 – v4
+
+v4 aims to solve a number of sore spots, particularly with caching, largely by leveraging libraries from the https://github.com/gql-dart ecosystem. There has also been a concerted effort to add more API docstrings to the codebase.
+
+## Cache overhaul
+
+- There is now only a single `GraphQLCache`, which leverages [normalize](https://pub.dev/packages/normalize),
+  Giving us a much more `apollo`ish api including `typePolicies`
+- `LazyCacheMap` has been deleted
+- `GraphQLCache` marks itself for rebroadcasting (should fix some related issues)
+- **`Store`** is now a seperate concern:
+
+```dart
+/// Only necessary on flutter
+void main() async {
+  await initHiveForFlutter();
+  runApp(MyApp());
+}
+
+GraphQLCache(
+  // The default store is the InMemoryStore, which does NOT persist to disk
+  store: await HiveStore.open(),
+)
+```
+
+## We now use the [gql_link system](https://github.com/gql-dart/gql/tree/master/links/gql_link)
+
+- Most links are re-exported from `graphql/client.dart`
+- `QueryOptions`, `MutationOptions`, etc are turned into
+  [gql_exec](https://github.com/gql-dart/gql/tree/master/links/gql_exec) `Request`s
+  before being sent down the link chain.
+- `documentNode` is deprecated in favor of `DocumentNode document` for consistency with `gql` libraries
+- We won't leave alpha until we have [full backwards compatability](https://github.com/gql-dart/gql/issues/57)
+
+```diff
+final httpLink = HttpLink(
+-  uri: 'https://api.github.com/graphql',
++  'https://api.github.com/graphql',
+);
+
+final authLink = AuthLink(
+  getToken: () async => 'Bearer $YOUR_PERSONAL_ACCESS_TOKEN',
+);
+
+var link = authLink.concat(httpLink);
+
+if (ENABLE_WEBSOCKETS) {
+  final websocketLink = WebSocketLink(
+-    uri: 'ws://localhost:8080/ws/graphql'
++    'ws://localhost:8080/ws/graphql'
+  );
+
+-  link = link.concat(websocketLink);
++  // split request based on type
++  link = Link.split(
++    (request) => request.isSubscription,
++    websocketLink,
++    link,
++  );
+}
+```
+
+This makes all link development coordinated across the ecosystem, so that we can leverage existing links like [gql_dio_link](https://pub.dev/packages/gql_dio_link), and all link-based clients benefit from new link development
+
+## `subscription` API overhaul
+
+`Subscription`/`client.subscribe` API is in line with the rest of the API
+
+```dart
+final subscriptionDocument = gql(
+  r'''
+    subscription reviewAdded {
+      reviewAdded {
+        stars, commentary, episode
+      }
+    }
+  ''',
+);
+// graphql/client.dart usage
+subscription = client.subscribe(
+  SubscriptionOptions(
+    document: subscriptionDocument
+  ),
+);
+
+// graphql_flutter/graphql_flutter.dart usage
+Subscription(
+  options: SubscriptionOptions(
+    document: subscriptionDocument,
+  ),
+  builder: (result) { /*...*/ },
+);
+```
+
+## Minor changes
+
+- As mentioned before, `documentNode: gql(...)` is now `document: gql(...)`.
+- The exported `gql` utility adds `__typename` automatically.
+  \*\*If you define your own, make sure to include `AddTypenameVisitor`,
+  or else that your cache `dataIdFromObject` works without it
+
+### Enums are normalized and idiomatic
+
+```diff
+- QueryResultSource.OptimisticResult
++ QueryResultSource.optimisticResult
+- QueryResultSource.Cache
++ QueryResultSource.cache
+// etc
+
+- QueryLifecycle.UNEXECUTED
++ QueryLifecycle.unexecuted
+- QueryLifecycle.SIDE_EFFECTS_PENDING
++ QueryLifecycle.sideEffectsPending
+```
+
+### `client.fetchMore` (experimental)
+
+The `fetchMore` logic is now available for when one isn't using `watchQuery`:
+
+```dart
+/// Untested example code
+class MyQuery {
+  QueryResult latestResult;
+  QueryOptions initialOptions;
+
+  FetchMoreOptions get _fetchMoreOptions {
+    // resolve the fetchMore params based on some data in lastestResult,
+    // like last item id or page number, and provide custom updateQuery logic
+  }
+
+  Future<QueryResult> fetchMore() async {
+    final result = await client.fetchMore(
+      _fetchMoreOptions,
+      options: options,
+      previousResult: latestResult,
+    );
+    _latestResult = result;
+    return result;
+  }
+}
+```

examples/flutter_bloc/lib/blocs/repos/my_repos_bloc.dart

@@ -107,13 +107,12 @@ class MyGithubReposBloc extends Bloc<MyGithubReposEvent, MyGithubReposState> {
         return;
       }
 
-      var mutatedRepo =
-          extractRepositoryData(queryResults.data) as LazyCacheMap;
+      var mutatedRepo = extractRepositoryData(queryResults.data);
 
       final notloadingRepo = Repo(
         id: repo.id,
         name: repo.name,
-        viewerHasStarred: mutatedRepo.data['viewerHasStarred'],
+        viewerHasStarred: mutatedRepo['viewerHasStarred'],
         isLoading: false,
       );
 

examples/flutter_bloc/lib/extended_bloc.dart

@@ -139,8 +139,8 @@ class _ExtendedBlocState extends State<ExtendedBloc> {
 }
 
 String parseOperationException(OperationException error) {
-  if (error.clientException != null) {
-    final exception = error.clientException;
+  if (error.linkException != null) {
+    final exception = error.linkException;
 
     if (exception is NetworkException) {
       return 'Failed to connect to ${exception.uri}';

examples/flutter_bloc/lib/extended_bloc/graphql/bloc.dart

@@ -3,7 +3,6 @@ import 'dart:async';
 import 'package:bloc/bloc.dart';
 import 'package:graphql/client.dart';
 import 'package:meta/meta.dart';
-import 'package:graphql/internal.dart';
 
 import 'package:graphql_flutter_bloc_example/extended_bloc/graphql/event.dart';
 import 'package:graphql_flutter_bloc_example/extended_bloc/graphql/state.dart';

examples/flutter_bloc/lib/extended_bloc/repositories_bloc.dart

@@ -10,7 +10,7 @@ class RepositoriesBloc extends GraphqlBloc<Map<String, dynamic>> {
           client: client,
           options: options ??
               WatchQueryOptions(
-                documentNode: parseString(r'''
+                document: parseString(r'''
                   query ReadRepositories($nRepositories: Int!, $after: String) {
                       viewer {
                         repositories(first: $nRepositories, after: $after) {

examples/flutter_bloc/lib/main.dart

@@ -44,9 +44,7 @@ class MyApp extends StatelessWidget {
   }
 
   GraphQLClient _client() {
-    final HttpLink _httpLink = HttpLink(
-      uri: 'https://api.github.com/graphql',
-    );
+    final HttpLink _httpLink = HttpLink('https://api.github.com/graphql');
 
     final AuthLink _authLink = AuthLink(
       getToken: () => 'Bearer $YOUR_PERSONAL_ACCESS_TOKEN',
@@ -55,9 +53,7 @@ class MyApp extends StatelessWidget {
     final Link _link = _authLink.concat(_httpLink);
 
     return GraphQLClient(
-      cache: OptimisticCache(
-        dataIdFromObject: typenameDataIdFromObject,
-      ),
+      cache: GraphQLCache(),
       link: _link,
     );
   }

examples/flutter_bloc/lib/repository.dart

@@ -16,7 +16,7 @@ class GithubRepository {
 
   Future<QueryResult> getRepositories(int numOfRepositories) async {
     final WatchQueryOptions _options = WatchQueryOptions(
-      documentNode: parseString(queries.readRepositories),
+      document: parseString(queries.readRepositories),
       variables: <String, dynamic>{
         'nRepositories': numOfRepositories,
       },
@@ -32,7 +32,7 @@ class GithubRepository {
         repo.viewerHasStarred ? mutations.removeStar : mutations.addStar;
 
     final MutationOptions _options = MutationOptions(
-      documentNode: parseString(document),
+      document: parseString(document),
       variables: <String, String>{
         'starrableId': repo.id,
       },

examples/flutter_bloc/pubspec.yaml

@@ -9,12 +9,10 @@ environment:
 dependencies:
   flutter:
     sdk: flutter
-
   graphql:
     path: ../../packages/graphql
   cupertino_icons: ^0.1.2
-  flutter_bloc: ^3.2.0
-  gql: 0.12.2
+  flutter_bloc: ^4.0.0
   equatable: ^0.2.0
 
 dev_dependencies:

examples/flutter_bloc/test/bloc_test.dart

@@ -77,7 +77,7 @@ void main() {
         final results = QueryResult(
           data: decodeGithubResponse['data'],
           exception: null,
-          loading: false,
+          source: QueryResultSource.network,
         );
 
         when(

examples/starwars/ios/Runner.xcodeproj/project.pbxproj

@@ -315,7 +315,6 @@
 /* Begin XCBuildConfiguration section */
 		249021D3217E4FDB00AE95B9 /* Profile */ = {
 			isa = XCBuildConfiguration;
-			baseConfigurationReference = 7AFA3C8E1D35360C0083082E /* Release.xcconfig */;
 			buildSettings = {
 				ALWAYS_SEARCH_USER_PATHS = NO;
 				CLANG_ANALYZER_NONNULL = YES;
@@ -387,7 +386,6 @@
 		};
 		97C147031CF9000F007C117D /* Debug */ = {
 			isa = XCBuildConfiguration;
-			baseConfigurationReference = 9740EEB21CF90195004384FC /* Debug.xcconfig */;
 			buildSettings = {
 				ALWAYS_SEARCH_USER_PATHS = NO;
 				CLANG_ANALYZER_NONNULL = YES;
@@ -441,7 +439,6 @@
 		};
 		97C147041CF9000F007C117D /* Release */ = {
 			isa = XCBuildConfiguration;
-			baseConfigurationReference = 7AFA3C8E1D35360C0083082E /* Release.xcconfig */;
 			buildSettings = {
 				ALWAYS_SEARCH_USER_PATHS = NO;
 				CLANG_ANALYZER_NONNULL = YES;

examples/starwars/lib/client_provider.dart

@@ -12,30 +12,22 @@ String uuidFromObject(Object object) {
   return null;
 }
 
-final OptimisticCache cache = OptimisticCache(
-  dataIdFromObject: uuidFromObject,
-);
-
 ValueNotifier<GraphQLClient> clientFor({
   @required String uri,
   String subscriptionUri,
 }) {
-  Link link = HttpLink(uri: uri);
+  Link link = HttpLink(uri);
   if (subscriptionUri != null) {
     final WebSocketLink websocketLink = WebSocketLink(
-      url: subscriptionUri,
-      config: SocketClientConfig(
-        autoReconnect: true,
-        inactivityTimeout: Duration(seconds: 30),
-      ),
+      subscriptionUri,
     );
 
-    link = link.concat(websocketLink);
+    link = Link.split((request) => request.isSubscription, websocketLink, link);
   }
 
   return ValueNotifier<GraphQLClient>(
     GraphQLClient(
-      cache: cache,
+      cache: GraphQLCache(store: HiveStore()),
       link: link,
     ),
   );

examples/starwars/lib/episode/hero_query.dart

@@ -12,7 +12,7 @@ class HeroForEpisode extends StatelessWidget {
   Widget build(BuildContext context) {
     return Query(
       options: QueryOptions(
-        documentNode: gql(r'''
+        document: gql(r'''
           query HeroForEpisode($ep: Episode!) {
             hero(episode: $ep) {
               __typename
@@ -40,7 +40,7 @@ class HeroForEpisode extends StatelessWidget {
           return Text(result.exception.toString());
         }
 
-        if (result.loading) {
+        if (result.isLoading) {
           return const Center(
             child: CircularProgressIndicator(),
           );

examples/starwars/lib/main.dart

@@ -1,6 +1,5 @@
-import 'dart:io';
-
 import 'package:flutter/material.dart';
+import 'package:graphql_flutter/graphql_flutter.dart';
 import 'package:universal_platform/universal_platform.dart';
 
 import './client_provider.dart';
@@ -20,7 +19,10 @@ String get host {
 final graphqlEndpoint = 'http://$host:3000/graphql';
 final subscriptionEndpoint = 'ws://$host:3000/subscriptions';
 
-void main() => runApp(MyApp());
+void main() async {
+  await initHiveForFlutter();
+  runApp(MyApp());
+}
 
 class MyApp extends StatelessWidget {
   @override

examples/starwars/lib/reviews/review.dart

@@ -1,4 +1,5 @@
 import 'package:meta/meta.dart';
+import 'package:flutter/material.dart';
 
 import '../episode/episode.dart';
 
@@ -43,3 +44,29 @@ class Review {
 }
 
 const String Function(Object jsonObject) displayReview = getPrettyJSONString;
+
+class DisplayReviews extends StatelessWidget {
+  const DisplayReviews({
+    Key key,
+    @required this.reviews,
+  }) : super(key: key);
+
+  final List<Map<String, dynamic>> reviews;
+
+  @override
+  Widget build(BuildContext context) {
+    return ListView(
+      padding: const EdgeInsets.all(8.0),
+      children: reviews
+          .map(displayReview)
+          .map<Widget>((String s) => Card(
+                child: Container(
+                  padding: const EdgeInsets.all(15.0),
+                  //height: 150,
+                  child: Text(s),
+                ),
+              ))
+          .toList(),
+    );
+  }
+}