GraphQL Flutter

https://github.com/zino-hofmann/graphql-flutter
Admin
GraphQL Flutter is a client implementation and collection of packages designed to work with GraphQL...
Tokens:14,314
Snippets:186
Trust Score:7.1
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Run GraphQL Example Commands

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/example/README.md

Commands to list repositories, star, or unstar a repository using the example CLI tool.

```sh
# List repositories
pub run example

# Star Repository (you can get repository ids from `pub run example`)
pub run example -a star --id $REPOSITORY_ID

# Unstar Repository
pub run example -a unstar --id $REPOSITORY_ID
```

--------------------------------

### Simple Commit Example

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/docs/dev/MAINTAINERS.md

A basic commit message example following the required header format.

```text
docs(changelog): update changelog to beta.5
```

--------------------------------

### Complete mutation example with cache fragment updates

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql_flutter/README.md

A comprehensive example showing mutation execution, cache fragment writing, and optimistic UI handling.

```dart
// final Map<String, Object> repository;
// final bool optimistic;
// Map<String, Object> extractRepositoryData(Map<String, Object> data);
// Map<String, dynamic> get expectedResult;
Mutation(
  options: MutationOptions(
    document: gql(starred ? mutations.removeStar : mutations.addStar),
    update: (cache, result) {
      if (result.hasException) {
        print(result.exception);
      } else {
        final updated = {
          ...repository,
          ...extractRepositoryData(result.data),
        };
        cache.writeFragment(
          Fragment(
              document: gql(
            '''
              fragment fields on Repository {
                id
                name
                viewerHasStarred
              }
            ''',
            // helper for constructing FragmentRequest
          )).asRequest(idFields: {
            '__typename': updated['__typename'],
            'id': updated['id'],
          }),
          data: updated,
          broadcast: false,
        );
      }
    },
    onError: (OperationException error) { },
    onCompleted: (dynamic resultData) { },
  ),
  builder: (RunMutation toggleStar, QueryResult result) {
    return ListTile(
      leading: starred
          ? const Icon(
              Icons.star,
              color: Colors.amber,
            )
          : const Icon(Icons.star_border),
      trailing: result.isLoading || optimistic
          ? const CircularProgressIndicator()
          : null,
      title: Text(repository['name'] as String),
      onTap: () {
        toggleStar(
          {'starrableId': repository['id']},
          optimisticResult: expectedResult,
        );
      },
    );
  },
)
```

--------------------------------

### Start Star Wars Server

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/examples/starwars/README.md

Executes the build and server startup process in the background.

```bash
make && make server !&
```

--------------------------------

### Install graphql_flutter

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql_flutter/README.md

Add the package dependency to your Flutter project.

```console
$ flutter pub add graphql_flutter
```

--------------------------------

### Detailed Commit Example

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/docs/dev/MAINTAINERS.md

A commit message example including a body to explain the reasoning behind a fix.

```text
fix(release): need to depend on latest rxjs and zone.js

The version in our package.json gets copied to the one we publish, and users need the latest of these.
```

--------------------------------

### Define GraphQL Query

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql_flutter/README.md

Example of a .graphql file definition for use with code generation.

```graphql
  query ReadRepositories($nRepositories: Int!) {
    viewer {
      repositories(last: $nRepositories) {
        nodes {
          id
          name
        }
      }
    }
  }
```

--------------------------------

### Install GraphQL Package

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

Add the graphql package to your Flutter project using the console.

```console
$ flutter pub add graphql
```

--------------------------------

### Check Java Version

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql_flutter/README.md

Verify the installed Java version for Android builds.

```sh
java -version
```

--------------------------------

### Composing Links

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

Examples of using Link.from, concat, and split to build complex link chains for GraphQL operations.

```dart
// kitchen sink:
Link.from([
  // common links run before every request
  DedupeLink(), // dedupe requests
  ErrorLink(onException: reportClientException),
]).split( // split terminating links, or they will break
  (request) => request.isSubscription,
  MyCustomSubscriptionAuthLink().concat(
    WebSocketLink(mySubscriptionEndpoint),
  ), // MyCustomSubscriptionAuthLink is only applied to subscriptions
  AuthLink(getToken: httpAuthenticator).concat(
    HttpLink(myAppEndpoint),
  )
);
// adding links after here would be pointless, as they would never be accessed

/// both `Link.from` and `link.concat` can be used to chain links:
final Link _link = _authLink.concat(_httpLink);
final Link _link = Link.from([_authLink, _httpLink]);

/// `Link.split` and `link.split` route requests to the left or right based on some condition
/// for instance, if you do `authLink.concat(httpLink).concat(websocketLink)`,
/// `websocketLink` won't see any `subscriptions`
link = Link.split((request) => request.isSubscription, websocketLink, link);
```

--------------------------------

### Commit Body with Stacktrace

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/docs/dev/MAINTAINERS.md

An example of a commit body containing technical details and a stacktrace for indexing purposes.

```text
checker: fixes overloading operation when the type is optimized

The stacktrace is the following one

} expected `Foo` not `Foo` - both operands must be the same type for operator overloading
   11 | }
   12 |
   13 | fn (_ Foo) == (_ Foo) bool {
      |                  ~~~
   14 |     return true
   15 | }


Signed-off-by: Vincenzo Palazzo <vincenzopalazzodev@gmail.com>
```

--------------------------------

### Create a new git branch for features

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/CONTRIBUTING.md

Use this command to start a new branch based on the beta branch for new features.

```shell
git checkout -b my-fix-branch beta
```

--------------------------------

### Querying with Typename for Normalization

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

A query example demonstrating the inclusion of __typename, which is required for the cache to resolve fragments correctly.

```graphql

query {
  people {
    __typename # Needed to decide where which entry to update in the cache
    ... on Employee {
      name
      age
    }
    ... on Customer {
      name
      age
    }
  }
}

```

--------------------------------

### GraphQL Schema Interface and Union Definitions

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

Example schema definitions for interfaces and unions requiring a possible types map.

```graphql

interface PersonI {
  name: String
  age: Int
}

type Employee implements PersonI {
  name: String
  age: Int
  daysOfEmployement: Int
}

type InStoreCustomer implements PersonI {
  name: String
  age: Int
  numberOfPurchases: Int
}

type OnlineCustomer implements PersonI {
  name: String
  age: Int
  numberOfPurchases: Int
}

union CustomerU = OnlineCustomer | InStoreCustomer

```

--------------------------------

### Server-side WebSocket Auth Logic

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

Example of server-side logic to close a connection if the token is invalid.

```typescript
subscriptions: {
    'graphql-ws': {
        onConnect: async (context: any) => {
            const { connectionParams } = context;

            if (!connectionParams) {
                throw new Error('Connection params are missing');
            }

            const authToken = connectionParams.authorization;

            if (authToken) {
                const isValid await authService.isTokenValid(authToken);

                if (!isValid) {
                    context.extra.socket.close(4001, 'Unauthorized');
                }

                return;
            }
        },
    },
},
```

--------------------------------

### Create a new git branch for fixes

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/CONTRIBUTING.md

Use this command to start a new branch based on the master branch for bug fixes.

```shell
git checkout -b my-fix-branch master
```

--------------------------------

### Custom Data ID Normalization

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

An example of a custom data ID function for versioned entities to prevent cache collisions.

```dart
String customDataIdFromObject(Map<String, Object> data) {
    final typeName = data['__typename'];
    final entityId = data['entityId'];
    final version = data['version'];
    if (typeName == null || entityId == null || version == null){
      return null;
    }
    return '${typeName}/${entityId}/${version}';
}
```

--------------------------------

### Initialize GraphQLClient

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql_flutter/README.md

Set up the GraphQLClient with HttpLink, AuthLink, and HiveStore for persistence.

```dart
...

import 'package:graphql_flutter/graphql_flutter.dart';

void main() async {

  // We're using HiveStore for persistence,
  // so we need to initialize Hive.
  await initHiveForFlutter();

  final HttpLink httpLink = HttpLink(
    'https://api.github.com/graphql',
  );

  final AuthLink authLink = AuthLink(
    getToken: () async => 'Bearer <YOUR_PERSONAL_ACCESS_TOKEN>',
    // OR
    // getToken: () => 'Bearer <YOUR_PERSONAL_ACCESS_TOKEN>',
  );

  final Link link = authLink.concat(httpLink);

  ValueNotifier<GraphQLClient> client = ValueNotifier(
    GraphQLClient(
      link: link,
      // The default store is the InMemoryStore, which does NOT persist to disk
      cache: GraphQLCache(store: HiveStore()),
    ),
  );

  ...
}
```

--------------------------------

### Initialize GraphQL Client

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

Create a GraphQLClient instance with HttpLink, AuthLink, and optional WebSocketLink for subscriptions.

```dart
// ...

final _httpLink = HttpLink(
  'https://api.github.com/graphql',
);

final _authLink = AuthLink(
  getToken: () async => 'Bearer $YOUR_PERSONAL_ACCESS_TOKEN',
);

Link _link = _authLink.concat(_httpLink);

/// subscriptions must be split otherwise `HttpLink` will. swallow them
if (websocketEndpoint != null){
  final _wsLink = WebSocketLink(websockeEndpoint);
  _link = Link.split((request) => request.isSubscription, _wsLink, _link);
}

final GraphQLClient client = GraphQLClient(
  /// **NOTE** The default store is the InMemoryStore, which does NOT persist to disk
  cache: GraphQLCache(),
  link: _link,
);

// ...
```

--------------------------------

### Update Link Configuration

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/changelog-v3-v4.md

Demonstrates the transition to the new link system, including positional arguments for links and the use of Link.split for conditional routing.

```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,
+  );
}
```

--------------------------------

### Configure default policies for GraphQLClient

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

Shows how to set global default policies during the initialization of the GraphQLClient.

```dart
GraphQLClient(
 defaultPolicies: DefaultPolicies(
    // make watched mutations behave like watched queries.
    watchMutation: Policies(
      FetchPolicy.cacheAndNetwork,
      ErrorPolicy.none,
      CacheRereadPolicy.mergeOptimistic,
    ),
  ),
  // ...
)
```

--------------------------------

### Run Flutter Client

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/examples/starwars/README.md

Commands to launch the Flutter application on iOS or web platforms.

```bash
flutter run
```

```bash
flutter run -d chrome
```

--------------------------------

### Create Query Options

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

Configure QueryOptions with the document and variables.

```dart

const int nRepositories = 50;

final QueryOptions options = QueryOptions(
  document: gql(readRepositories),
  variables: <String, dynamic>{
    'nRepositories': nRepositories,
  },
);
```

--------------------------------

### Generate package changelogs

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/docs/dev/MAINTAINERS.md

Set the GitHub token and execute the appropriate make command to generate changelogs for specific packages or the entire project.

```bash
export GITHUB_TOKEN="your_token"
make {changelog_client|changelog_flutter|changelog}
```

--------------------------------

### Project Directory Structure

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/ARCHITECTURE.md

Displays the top-level directory structure of the project using the tree command.

```bash
tree -L 3 -d .
.
├── example
│   ├── bin
│   └── lib
├── lib
│   └── src
│       ├── cache      # cache and store abstractions
│       ├── core       # 
│       ├── exceptions # client exceptions / link exception wrappers
│       ├── links      # custom and re-exported gql_links
│       ├── scheduler  # used by ObservableQuery for polling
│       └── utilities  # helpers like gql
└── test
    └── cache
```

--------------------------------

### Core Module Directory Structure

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/ARCHITECTURE.md

Displays the file structure within the lib/src/core directory.

```bash
tree lib/src/core
├── _base_options.dart # shared base class for *Options classes
├── _data_class.dart   # stopgap helper for a truly immutable options API
├── _query_write_handling.dart # some common write handling extracted from
│                              # the QueryManager.
├── core.dart             # reexports.
├── fetch_more.dart       # shared fetchMore logic.
├── mutation_options.dart # MutationOptions and MutationCallbackHandler.
├── observable_query.dart # the guts of watchQuery/watchMutation.
├── policies.dart         # Policies and default policies.
├── query_manager.dart    # The central execution entrypoints for
│                         # query, mutate, and subscribe.
├── query_options.dart    # QueryOptions, WatchQueryOptions, FetchMoreOptions
└── query_result.dart     # QueryResult and MultiSourceResult
```

--------------------------------

### Execute File Upload

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

Use MultipartFile to prepare files for upload and include them in the mutation variables.

```dart
import "package:http/http.dart" show Multipartfile;
import "package:http_parser/http_parser.dart" show MediaType;

// ...

final myFile = MultipartFile.fromString(
  "",
  "just plain text",
  filename: "sample_upload.txt",
  contentType: MediaType("text", "plain"),
);

final result = await graphQLClient.mutate(
  MutationOptions(
    document: gql(uploadMutation),
    variables: {
      'files': [myFile],
    },
  )
);
```

--------------------------------

### Wrap App with GraphQLProvider

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql_flutter/README.md

Provide the GraphQL client to the widget tree by wrapping the MaterialApp.

```dart
  ...

  return GraphQLProvider(
    client: client,
    child: MaterialApp(
      title: 'Flutter Demo',
      ...
    ),
  );

  ...
```

--------------------------------

### Configuring Hive Persistence

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/changelog-v3-v4.md

Initialize Hive for Flutter and configure the GraphQLCache to use HiveStore for disk persistence.

```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: GraphQLCache(store: HiveStore()),
)
```

--------------------------------

### Configure Android Build Settings

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql_flutter/README.md

Update build.gradle to target Java 17 for compile and Kotlin options.

```gradle
android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }

    kotlinOptions {
        jvmTarget = "17"
    }
}
```

--------------------------------

### Define a GraphQL mutation

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

Create a .graphql file to define the mutation structure for code generation.

```graphql
# add_star.graphql
mutation AddStar($starrableId: ID!) {
  action: addStar(input: { starrableId: $starrableId }) {
    starrable {
      viewerHasStarred
    }
  }
}
```

--------------------------------

### Import graphql_flutter

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql_flutter/README.md

Import the package into your Dart files.

```dart
import 'package:graphql_flutter/graphql_flutter.dart';
```

--------------------------------

### Subscription Widget Implementation

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql_flutter/README.md

Uses the Subscription widget to handle real-time updates and display results.

```dart
final subscriptionDocument = gql(
  r'''
    subscription reviewAdded {
      reviewAdded {
        stars, commentary, episode
      }
    }
  ''',
);

class _MyHomePageState extends State<MyHomePage> {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: Subscription(
          options: SubscriptionOptions(
            document: subscriptionDocument,
          ),
          builder: (result) {
            if (result.hasException) {
              return Text(result.exception.toString());
            }

            if (result.isLoading) {
              return Center(
                child: const CircularProgressIndicator(),
              );
            }
            // ResultAccumulator is a provided helper widget for collating subscription results.
            // careful though! It is stateful and will discard your results if the state is disposed
            return ResultAccumulator.appendUniqueEntries(
              latest: result.data,
              builder: (context, {results}) => DisplayReviews(
                reviews: results.reversed.toList(),
              ),
            );
          }
        ),
      )
    );
  }
}
```

--------------------------------

### Execute Query

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

Run the query using the client and handle the result.

```dart
// ...

final QueryResult result = await client.query(options);

if (result.hasException) {
  print(result.exception.toString());
}

final List<dynamic> repositories =
    result.data['viewer']['repositories']['nodes'] as List<dynamic>;

// ...
```

--------------------------------

### Implement Subscription API

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/changelog-v3-v4.md

Shows the updated subscription usage for both the core client and the Flutter widget, ensuring consistency with the new API structure.

```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) { /*...*/ },
);
```

--------------------------------

### Configure Persistent Cache

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

Use HiveStore to enable disk persistence for the GraphQL cache.

```dart
GraphQLClient getClient() async {
  ...
  /// initialize Hive and wrap the default box in a HiveStore
  final store = await HiveStore.open(path: 'my/cache/path');
  return GraphQLClient(
      /// pass the store to the cache for persistence
      cache: GraphQLCache(store: store),
      link: _link,
  );
}
```

--------------------------------

### Initialize Flutter Web Service Worker

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql_flutter/example/web/index.html

Handles service worker registration and fallback to main.dart.js if the service worker fails or is unsupported.

```javascript
var serviceWorkerVersion = null; var scriptLoaded = false; function loadMainDartJs() { if (scriptLoaded) { return; } scriptLoaded = true; var scriptTag = document.createElement('script'); scriptTag.src = 'main.dart.js'; scriptTag.type = 'application/javascript'; document.body.append(scriptTag); } if ('serviceWorker' in navigator) { // Service workers are supported. Use them. window.addEventListener('load', function () { // Wait for registration to finish before dropping the <script> tag. // Otherwise, the browser will load the script multiple times, // potentially different versions. var serviceWorkerUrl = 'flutter_service_worker.js?v=' + serviceWorkerVersion; navigator.serviceWorker.register(serviceWorkerUrl) .then((reg) => { function waitForActivation(serviceWorker) { serviceWorker.addEventListener('statechange', () => { if (serviceWorker.state == 'activated') { console.log('Installed new service worker.'); loadMainDartJs(); } }); } if (!reg.active && (reg.installing || reg.waiting)) { // No active web worker and we have installed or are installing // one for the first time. Simply wait for it to activate. waitForActivation(reg.installing || reg.waiting); } else if (!reg.active.scriptURL.endsWith(serviceWorkerVersion)) { // When the app updates the serviceWorkerVersion changes, so we // need to ask the service worker to update. console.log('New service worker available.'); reg.update(); waitForActivation(reg.installing); } else { // Existing service worker is still good. console.log('Loading app from service worker.'); loadMainDartJs(); } }); // If service worker doesn't succeed in a reasonable amount of time, // fallback to plaint <script> tag. setTimeout(() => { if (!scriptLoaded) { console.warn( 'Failed to load app from service worker. Falling back to plain <script> tag.', ); loadMainDartJs(); } }, 4000); }); } else { // Service workers not supported. Just drop the <script> tag. loadMainDartJs(); }
```

--------------------------------

### Perform Query-based Cache Operations

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

Demonstrates creating a Request object and using it to read from or write to the cache.

```dart
const int nRepositories = 50;

final QueryOptions options = QueryOptions(
  document: gql(readRepositories),
  variables: {
    'nRepositories': nRepositories,
  },
);

var queryRequest = Request(
  operation: Operation(
    document: gql(readRepositories),
  ),
  variables: {
    'nRepositories': nRepositories,
  },
);

/// experimental convenience api
queryRequest = Operation(document: gql(readRepositories)).asRequest(
  variables: {
    'nRepositories': nRepositories,
  },
);

print(queryRequest == options.asRequest);

final data = client.readQuery(queryRequest);
client.writeQuery(queryRequest, data);
```

--------------------------------

### Subscribe to GraphQL Events

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

Define a subscription document and listen to incoming events.

```dart
final subscriptionDocument = gql(
  r'''
    subscription reviewAdded {
      reviewAdded {
        stars, commentary, episode
      }
    }
  ''',
);
// graphql/client.dart usage
subscription = client.subscribe(
  SubscriptionOptions(
    document: subscriptionDocument
  ),
);
subscription.listen(reactToAddedReview)
```

--------------------------------

### Configure Mutation Options

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

Use MutationOptions to pass the document and variables to the mutation.

```dart
// ...

final MutationOptions options = MutationOptions(
  document: gql(addStar),
  variables: <String, dynamic>{
    'starrableId': repositoryID,
  },
);

// ...
```

--------------------------------

### Push branch to remote

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/CONTRIBUTING.md

Uploads the local branch to the origin repository.

```shell
git push origin my-fix-branch
```

--------------------------------

### Define FetchMoreOptions for Pagination

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql_flutter/README.md

Configure FetchMoreOptions to merge new paginated results with existing data.

```dart
...
// this is returned by the GitHubs GraphQL API for pagination purpose
final Map pageInfo = result.data['search']['pageInfo'];
final String fetchMoreCursor = pageInfo['endCursor'];

/// **NOTE**: with the addition of strict data structure checking in v4,
/// it is easy to make mistakes in writing [updateQuery].
///
/// To mitigate this, [FetchMoreOptions.partial] has been provided.
FetchMoreOptions opts = FetchMoreOptions(
  variables: {'cursor': fetchMoreCursor},
  updateQuery: (previousResultData, fetchMoreResultData) {
    // this function will be called so as to combine both the original and fetchMore results
    // it allows you to combine them as you would like
    final List<dynamic> repos = [
      ...previousResultData['search']['nodes'] as List<dynamic>,
      ...fetchMoreResultData['search']['nodes'] as List<dynamic>
    ];

    // to avoid a lot of work, lets just update the list of repos in returned
    // data with new data, this also ensures we have the endCursor already set
    // correctly
    fetchMoreResultData['search']['nodes'] = repos;

    return fetchMoreResultData;
  },
);

...
```

--------------------------------

### Configure Manual Connection Control

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

Use a PublishSubject to manually toggle the WebSocket connection state.

```dart
var toggleConnection = PublishSubject<ToggleConnectionState>;

SocketClientConfig(
    toggleConnection: toggleConnection,
),
```

--------------------------------

### Split Link for Subscriptions

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql_flutter/README.md

Configures a link to route subscription requests through a WebSocket link.

```dart
link = Link.split((request) => request.isSubscription, websocketLink, link);
```

--------------------------------

### Configuring Possible Types in GraphQLCache

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

Defining the possible types map and passing it to the GraphQLClient cache configuration.

```dart
const POSSIBLE_TYPES = const {
  'CustomerU': {'InStoreCustomer', 'OnlineCustomer'},
  'PersonI': {'Employee', 'InStoreCustomer', 'OnlineCustomer'},
}

// Here's how it's parsed to the cache
final client = GraphQLClient(
  cache: GraphQLCache(
    possibleTypes: POSSIBLE_TYPES,
  ),
)
```

--------------------------------

### Update Gradle Wrapper

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql_flutter/README.md

Set the distribution URL to Gradle 8.4 in gradle-wrapper.properties.

```properties
distributionUrl=https\://services.gradle.org/distributions/gradle-8.4-bin.zip
```

--------------------------------

### Implement experimental fetchMore

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/changelog-v3-v4.md

Use the client.fetchMore method for pagination or data fetching outside of 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,
      originalOptions: options,
      previousResult: latestResult,
    );
    latestResult = result;
    return result;
  }
}
```

--------------------------------

### Direct Cache Access Methods

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/changelog-v3-v4.md

Use these methods on the client instance to interact with the cache directly.

```dart
/// see more in graphql's readme
client.writeQuery(myQueryOptions.asRequest, queryData);
client.readQuery(myQueryOptions.asRequest);
```

--------------------------------

### Handling Operation Exceptions

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

Demonstrates how to check for exceptions in a QueryResult and handle specific link exceptions like network issues.

```dart
if (result.hasException) {
  if (result.exception.linkException is NetworkException) {
    // handle network issues, maybe
  }
  return Text(result.exception.toString())
}
```

--------------------------------

### Customizing WebSocket Connections with GraphQLWebSocketChannel

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

Use the connect parameter to supply custom headers or register listeners. Wrap the channel with .forGraphQL() to ensure the client can listen to stream events.

```dart
connect: (url, protocols) {
   var channel = WebSocketChannel.connect(url, protocols: protocols)
   // without this line, our client won't be able to listen to stream events,
   // because you are already listening.
   channel = channel.forGraphQL();
   channel.stream.listen(myListener)
   return channel;
}
```

--------------------------------

### Configuring AWS AppSync AuthLink

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

Shows how to configure an AuthLink with a JWT token for AWS Cognito User Pools.

```dart
// Where `session` is a CognitorUserSession
// from amazon_cognito_identity_dart_2
final token = session.getAccessToken().getJwtToken();

final AuthLink authLink = AuthLink(
  getToken: () => token,
);
```

--------------------------------

### Override policies for a single query

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

Demonstrates how to apply specific policies to an individual query request using QueryOptions.

```dart
// override policies for a single query
client.query(QueryOptions(
  // return result from network and save to cache.
  fetchPolicy: FetchPolicy.networkOnly,
  // ignore all GraphQL errors.
  errorPolicy: ErrorPolicy.ignore,
  // ignore cache data.
  cacheRereadPolicy: CacheRereadPolicy.ignore,
  // ...
));
```

--------------------------------

### Define a GraphQL mutation string

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql_flutter/README.md

Create a raw string containing the GraphQL mutation definition to be used with the gql parser.

```dart
String addStar = """
  mutation AddStar(\$starrableId: ID!) {
    addStar(input: {starrableId: \$starrableId}) {
      starrable {
        viewerHasStarred
      }
    }
  }
""";
```

--------------------------------

### Implementing a Custom Link for Dynamic WebSocket Reconnection

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

Create a custom Link class to manage WebSocket connections and update them dynamically when authentication tokens change.

```dart

class SocketCustomLink extends Link {
  SocketCustomLink(this.url);
  final String url;
  _Connection? _connection;

  /// this will be called every time you make a subscription
  @override
  Stream<Response> request(Request request, [forward]) async* {
    /// first get the token by your own way
    String? token = "...";

    /// check is connection is null or the token changed
    if (_connection == null || _connection!.token != token) {
      connectOrReconnect(token);
    }
    yield* _connection!.client.subscribe(request, true);
  }

  /// Connects or reconnects to the server with the specified headers.
  void connectOrReconnect(String? token) {
    _connection?.client.dispose();
    var _url = Uri.parse(url);
    if (kIsWeb) {
      /// web don't support headers in sockets so you may need to pass it as query string
      /// server must support that
      _url = _url.replace(queryParameters: {"access_token": token});
    }
    _connection = _Connection(
      client: SocketClient(
        _url.toString(),
        config: SocketClientConfig(
          autoReconnect: true,
          headers: kIsWeb || token == null
              ? null
              : {"Authorization": " Bearer $token"},
        ),
      ),
      token: token,
    );
  }

  @override
  Future<void> dispose() async {
    await _connection?.client.dispose();
    _connection = null;
  }
}

/// this a wrapper for web socket to hold the used token
class _Connection {
  SocketClient client;
  String? token;
  _Connection({
    required this.client,
    required this.token,
  });
}
```

--------------------------------

### Execute Query with Query Widget

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql_flutter/README.md

Use the Query widget to execute a GraphQL operation and build UI based on the result state.

```dart
// ...
Query(
  options: QueryOptions(
    document: gql(readRepositories), // this is the query string you just created
    variables: {
      'nRepositories': 50,
    },
    pollInterval: const Duration(seconds: 10),
  ),
  // Just like in apollo refetch() could be used to manually trigger a refetch
  // while fetchMore() can be used for pagination purpose
  builder: (QueryResult result, { VoidCallback? refetch, FetchMore? fetchMore }) {
    if (result.hasException) {
        return Text(result.exception.toString());
    }

    if (result.isLoading) {
      return const Text('Loading');
    }

    List? repositories = result.data?['viewer']?['repositories']?['nodes'];

    if (repositories == null) {
      return const Text('No repositories');
    }

    return ListView.builder(
      itemCount: repositories.length,
      itemBuilder: (context, index) {
        final repository = repositories[index];

        return Text(repository['name'] ?? '');
    });
  },
);
// ...
```

--------------------------------

### Subscription Hook Implementation

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql_flutter/README.md

Uses the useSubscription hook within a HooksWidget to manage subscription state.

```dart
final subscriptionDocument = gql(
  r'''
    subscription reviewAdded {
      reviewAdded {
        stars, commentary, episode
      }
    }
  ''',
);

class MyHomePage extends HooksWidget {
  @override
  Widget build(BuildContext context) {
    final result = useSubscription(
      SubscriptionOptions(
        document: subscriptionDocument,
      ),
    );
    
    Widget child;
    if (result.hasException) {
      child = Text(result.exception.toString());
    } else if (result.isLoading) {
      child = Center(
        child: const CircularProgressIndicator(),
      );
    } else {
      child = ResultAccumulator.appendUniqueEntries(
        latest: result.data,
        builder: (context, {results}) => DisplayReviews(
          reviews: results.reversed.toList(),
        ),
      );    
    }
    return Scaffold(
      body: Center(child: child)
    );
  }
}
```

--------------------------------

### Execute Mutation and Handle Response

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

Send the mutation to the server and process the resulting data or exceptions.

```dart
// ...

final QueryResult result = await client.mutate(options);

if (result.hasException) {
  print(result.exception.toString());
  return;
}

final bool isStarred =
    result.data['action']['starrable']['viewerHasStarred'] as bool;

if (isStarred) {
  print('Thanks for your star!');
  return;
}

// ...
```

--------------------------------

### Perform Fragment-based Cache Operations

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

Demonstrates creating a FragmentRequest and using it to read or write specific entity fragments in the cache.

```dart

final fragmentDoc = gql(
  r'''
    fragment mySmallSubset on MyType {
      myField,
      someNewField
    }
  ''',
);

var fragmentRequest = FragmentRequest(
  fragment: Fragment(
    document: fragmentDoc,
  ),
  idFields: {'__typename': 'MyType', 'id': 1},
);

/// same as experimental convenience api
fragmentRequest = Fragment(document: fragmentDoc).asRequest(
  idFields: {'__typename': 'MyType', 'id': 1},
);

final data = client.readFragment(fragmentRequest);
client.writeFragment(fragmentRequest, data);
```

--------------------------------

### Watch queries for reactive updates

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

Use watchQuery to listen to cache changes and server updates.

```dart
final observableQuery = client.watchQuery(
  WatchQueryOptions(
    fetchResults: true,
    document: gql(
      r'''
      query HeroForEpisode($ep: Episode!) {
        hero(episode: $ep) {
          name
        }
      }
      ''',
    ),
    variables: {'ep': 'NEWHOPE'},
  ),
);

/// Listen to the stream of results. This will include:
/// * `options.optimisitcResult` if passed
/// * The result from the server (if `options.fetchPolicy` includes networking)
/// * rebroadcast results from edits to the cache
observableQuery.stream.listen((QueryResult result) {
  if (!result.isLoading && result.data != null) {
    if (result.hasException) {
      print(result.exception);
      return;
    }
    if (result.isLoading) {
      print('loading');
      return;
    }
    doSomethingWithMyQueryResult(myCustomParser(result.data));
  }
});
// ... cleanup:
observableQuery.close();
```

--------------------------------

### Add Auth Headers to WebSocket

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

Use the initialPayload property to inject authentication headers into the WebSocket connection.

```dart
initialPayload: () {
    var headers = <String, String>{};
    headers.putIfAbsent(HttpHeaders.authorizationHeader, () => token);

    return headers;
},
```

--------------------------------

### Implement search-as-you-type with debouncing

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

Cancel previous search operations when new input is received to save resources.

```dart
CancellableOperation<QueryResult>? currentSearch;

void onSearchTextChanged(String query) {
  // Cancel previous search
  currentSearch?.cancel();
  
  // Start new search
  currentSearch = client.queryCancellable(
    QueryOptions(
      document: gql(searchQuery),
      variables: {'query': query},
    ),
  );
  
  currentSearch!.result.then((result) {
    if (!result.hasException) {
      updateSearchResults(result.data);
    }
  });
}
```

--------------------------------

### Access GraphQL Client with GraphQLConsumer

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql_flutter/README.md

Use GraphQLConsumer to retrieve the client instance from a context descended from a GraphQLProvider.

```dart
  ...

  return GraphQLConsumer(
    builder: (GraphQLClient client) {
      // do something with the client

      return Container(
        child: Text('Hello world'),
      );
    },
  );

  ...
```

--------------------------------

### Execute a mutation with the Mutation widget

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql_flutter/README.md

Use the Mutation widget to trigger GraphQL mutations and handle results or cache updates.

```dart
...

Mutation(
  options: MutationOptions(
    document: gql(addStar), // this is the mutation string you just created
    // you can update the cache based on results
    update: (GraphQLDataProxy cache, QueryResult result) {
      return cache;
    },
    // or do something with the result.data on completion
    onCompleted: (dynamic resultData) {
      print(resultData);
    },
  ),
  builder: (
    RunMutation runMutation,
    QueryResult result,
  ) {
    return FloatingActionButton(
      onPressed: () => runMutation({
        'starrableId': <A_STARTABLE_REPOSITORY_ID>,
      }),
      tooltip: 'Star',
      child: Icon(Icons.star),
    );
  },
);

...
```

--------------------------------

### Additional GraphQL Hooks

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql_flutter/README.md

Provides access to the client and observable query functionality via hooks.

```dart
final client = useGraphQLClient(); // Fetch the current client
final observableQuery = useWatchQuery(WatchQueryOptions(...)); // Watch a query
final mutationObservableQuery = useWatchMutation(WatchQueryOptions(...)); // Watch a query
```

--------------------------------

### Configure PersistedQueriesLink

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

Initialize and concatenate the PersistedQueriesLink with an HttpLink to enable automatic persisted queries.

```dart
final PersistedQueriesLink _apqLink = PersistedQueriesLink(
  // To enable GET queries for the first load to allow for CDN caching
  useGETForHashedQueries: true,
);

final HttpLink _httpLink = HttpLink(
  'https://api.url/graphql',
);

final Link _link = _apqLink.concat(_httpLink);
```

--------------------------------

### Commit Message Format

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/docs/dev/MAINTAINERS.md

The standard structure for all commit messages, consisting of a header, optional body, and footer.

```text
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
```

--------------------------------

### Execute a generated mutation

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

Use the generated client methods and options classes to execute mutations with type safety.

```dart
// add_star.dart
import 'add_star.graphql.dart';

// ..


  await client.mutateAddStar(
    OptionsMutationAddStar(
      variables: VariablesMutationAddStar(starableId: repositoryID)
    )
  );
```

--------------------------------

### Execute a mutation with the useMutation hook

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql_flutter/README.md

Use the useMutation hook to perform mutations within functional components.

```dart

// ...

final addStarMutation = useMutation(
  MutationOptions(
    document: gql(addStar), // this is the mutation string you just created
    // you can update the cache based on results
    update: (GraphQLDataProxy cache, QueryResult result) {
      return cache;
    },
    // or do something with the result.data on completion
    onCompleted: (dynamic resultData) {
      print(resultData);
    },
  ),
);
return FloatingActionButton(
  onPressed: () => addStarMutation.runMutation({
    'starrableId': <A_STARTABLE_REPOSITORY_ID>,
  }),
  tooltip: 'Star',
  child: Icon(Icons.star),
);

// ...
```

--------------------------------

### Define a GraphQL Query String

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql_flutter/README.md

Define a GraphQL query as a multiline string for use with the gql parser.

```dart
String readRepositories = """
  query ReadRepositories(\$nRepositories: Int!) {
    viewer {
      repositories(last: \$nRepositories) {
        nodes {
          id
          name
          viewerHasStarred
        }
      }
    }
  }
""";
```

--------------------------------

### Commit signed changes

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/CONTRIBUTING.md

Commits changes with a GPG signature and automatically stages edited files.

```shell
git commit -S -a
```

--------------------------------

### Execute Query with flutter-hooks

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql_flutter/README.md

Use the useQuery hook to execute a GraphQL operation within a functional widget.

```dart
// ...
final readRespositoriesResult = useQuery(
  QueryOptions(
    document: gql(readRepositories), // this is the query string you just created
    variables: {
      'nRepositories': 50,
    },
    pollInterval: const Duration(seconds: 10),
  ),
);
final result = readRespositoriesResult.result;

if (result.hasException) {
    return Text(result.exception.toString());
}

if (result.isLoading) {
  return const Text('Loading');
}

List? repositories = result.data?['viewer']?['repositories']?['nodes'];

if (repositories == null) {
  return const Text('No repositories');
}

return ListView.builder(
  itemCount: repositories.length,
  itemBuilder: (context, index) {
    final repository = repositories[index];

    return Text(repository['name'] ?? '');
});
// ...
```

--------------------------------

### Query Cache Access

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

Methods for reading and writing full queries to the cache using Request objects.

```APIDOC
## client.readQuery(Request request)

### Description
Reads data from the cache for a specific query request.

### Parameters
- **request** (Request) - Required - The request object containing the operation and variables.

## client.writeQuery(Request request, Map<String, dynamic> data)

### Description
Writes data to the cache for a specific query request, triggering automatic rebroadcasting.

### Parameters
- **request** (Request) - Required - The request object.
- **data** (Map<String, dynamic>) - Required - The data to write to the cache.
```

--------------------------------

### Refresh WebSocket Headers

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

Implement onConnectionLost to handle token refreshing when a connection is closed.

```dart
onConnectionLost: (int? code, String? reason) async {
    if (code == 4001) {
        await authTokenService.issueToken(refresh: true);
        return Duration.zero;
    }

    return null;
    }
```

--------------------------------

### Configure HttpLink for CSRF protection

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

Add required headers to HttpLink to resolve CSRF errors when uploading files to an Apollo GraphQL server.

```dart
HttpLink httpLink = HttpLink('https://api.url/graphql', defaultHeaders: {
  'Content-Type': 'application/json; charset=utf-8',
  'X-Apollo-Operation-Name': 'post'
})
```

--------------------------------

### Implement optimistic mutations

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql_flutter/README.md

Pass an optimisticResult to the mutation function to provide immediate UI feedback before the server responds.

```dart
...
FlutterWidget(
  onTap: () {
    toggleStar(
      { 'starrableId': repository['id'] },
      optimisticResult: {
        'action': {
          'starrable': {'viewerHasStarred': !starred}
        }
      },
    );
  },
)
...
```

--------------------------------

### Toggle Connection State

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

Send disconnect or connect commands to the toggleConnection stream.

```dart
toggleConnection.add(ToggleConnectionState.disconnect);
//OR
toggleConnection.add(ToggleConnectionState.connect);
```

--------------------------------

### Execute Generated Query Hook

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql_flutter/README.md

Utilize the generated hook to execute a query and handle loading or exception states.

```dart
final queryResult = useQueryReadRepositories(
  OptionsQueryReadRepositories(
    variables: VariablesQueryReadRepositories(
      nRepositories: 10
    )
  )
);
if (queryResult.result.hasException) {
  return Text(result.exception.toString());
}
if (queryResult.result.isLoading) {
  return Text(text: "LOADING");
}
final data = queryResult.result.parsedData;

return Column(
  children: data?.viewer.repositores.nodes.map((node) => Text(text: node.name));
);
```

--------------------------------

### Fragment Cache Access

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

Methods for reading and writing fragments to the cache using FragmentRequest objects.

```APIDOC
## client.readFragment(FragmentRequest request)

### Description
Reads a specific fragment from the cache based on the provided ID fields.

### Parameters
- **request** (FragmentRequest) - Required - The fragment request containing the fragment definition and idFields.

## client.writeFragment(FragmentRequest request, Map<String, dynamic> data)

### Description
Writes a fragment to the cache, triggering automatic rebroadcasting.

### Parameters
- **request** (FragmentRequest) - Required - The fragment request.
- **data** (Map<String, dynamic>) - Required - The data to write to the cache.
```

--------------------------------

### Cancel GraphQL operations with convenience methods

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

Use queryCancellable and mutateCancellable for automatic token management.

```dart
// Query with automatic token management
final operation = client.queryCancellable(
  QueryOptions(
    document: gql(readRepositories),
    variables: {'nRepositories': 50},
  ),
);

// Cancel anytime
operation.cancel();

// Get the result
final result = await operation.result;
```

```dart
// Mutation with automatic token management
final operation = client.mutateCancellable(
  MutationOptions(
    document: gql(addStar),
    variables: {'starrableId': repositoryID},
  ),
);

// Cancel if needed
operation.cancel();

final result = await operation.result;
```

--------------------------------

### Cancel GraphQL operations with CancellationToken

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

Manually manage operation lifecycle by creating and disposing of a CancellationToken.

```dart
import 'package:graphql/client.dart';

final cancellationToken = CancellationToken();

// Start a query
final resultFuture = client.query(
  QueryOptions(
    document: gql(readRepositories),
    variables: {'nRepositories': 50},
    cancellationToken: cancellationToken,
  ),
);

// Cancel it before completion
cancellationToken.cancel();

// The result will contain a CancelledException
final result = await resultFuture;
if (result.hasException) {
  if (result.exception!.linkException is CancelledException) {
    print('Operation was cancelled');
  }
}

// Clean up when done
cancellationToken.dispose();
```

--------------------------------

### Trigger Pagination with fetchMore

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql_flutter/README.md

Invoke the fetchMore function within a UI component to load additional data.

```dart
RaisedButton(
  child: Row(
    mainAxisAlignment: MainAxisAlignment.center,
    children: <Widget>[
      Text("Load More"),
    ],
  ),
  onPressed: () {
    fetchMore(opts);
  },
)
```

--------------------------------

### Supplying Custom Headers to SocketClient

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

Configure custom headers for WebSocket connections using SocketClientConfig. Note that custom headers are not supported on Flutter Web.

```dart
 SocketClient(
    wsUrl,
    config: SocketClientConfig(
      autoReconnect: autoReconnect,
      headers: customHeaders,
      delayBetweenReconnectionAttempts: delayBetweenReconnectionAttempts,
    ),
 );
```

--------------------------------

### Reset local master branch

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/CONTRIBUTING.md

Forces a checkout of the master branch.

```shell
git checkout master -f
```

--------------------------------

### GraphQL Upload Mutation Definition

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

Define a mutation that accepts files using the Upload scalar type.

```graphql
mutation($files: [Upload!]!) {
  multipleUpload(files: $files) {
    id
    filename
    mimetype
    path
  }
}
```

--------------------------------

### OperationException Class Structure

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

Defines the structure of the OperationException class used to capture GraphQL and link-level errors.

```dart
/// Container for both [graphqlErrors] returned from the server
/// and any [linkException] that caused a failure.
class OperationException implements Exception {
  /// Any graphql errors returned from the operation
  List<GraphQLError> graphqlErrors = [];

  /// Errors encountered during execution such as network or cache errors
  LinkException linkException;
}
```

--------------------------------

### Rebase and force push

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/CONTRIBUTING.md

Updates the branch with master changes and forces an update to the remote pull request.

```shell
git rebase master -i
git push -f
```

--------------------------------

### Update local master

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/CONTRIBUTING.md

Pulls the latest changes from the upstream master branch.

```shell
git pull --ff upstream master
```

--------------------------------

### Default Data ID Normalization

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

The default function used by GraphQLCache to generate unique keys for cached objects based on typename and ID fields.

```dart
String dataIdFromObject(Map<String, Object> data) {
  final typename = data['__typename'];
  if (typename == null) return null;

  final id = data['id'] ?? data['_id'];
  return id == null ? null : '$typename:$id';
}
```

--------------------------------

### Normalize Enums to idiomatic Dart

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/changelog-v3-v4.md

Update QueryResultSource and QueryLifecycle enum references to use camelCase instead of UPPER_CASE.

```diff
- QueryResultSource.OptimisticResult
+ QueryResultSource.optimisticResult
- QueryResultSource.Cache
+ QueryResultSource.cache
// etc

- QueryLifecycle.UNEXECUTED
+ QueryLifecycle.unexecuted
- QueryLifecycle.SIDE_EFFECTS_PENDING
+ QueryLifecycle.sideEffectsPending
```

--------------------------------

### Cancel operations on widget disposal

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql/README.md

Ensure network requests are aborted when a widget is removed from the tree.

```dart
class MyWidget extends StatefulWidget {
  @override
  _MyWidgetState createState() => _MyWidgetState();
}

class _MyWidgetState extends State<MyWidget> {
  CancellableOperation<QueryResult>? operation;

  @override
  void initState() {
    super.initState();
    operation = client.queryCancellable(
      QueryOptions(document: gql(myQuery)),
    );
  }

  @override
  void dispose() {
    operation?.cancel(); // Cancel when leaving screen
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    // Your widget tree
  }
}
```
Tokens:
Raw