### Running GraphQL Client Example Commands

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

These shell commands demonstrate how to interact with the Dart GraphQL client example application. You can list repositories, and star or unstar a specific repository using its ID. Repository IDs can be obtained by running the 'List repositories' command.

```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
```

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

### Start Star Wars Demo GraphQL Server

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

This command builds the server components and then runs the GraphQL server in the background, making its API available for client consumption.

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

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

### Example Git Commit Message: Documentation Update

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

Illustrates a concise Git commit message for documentation changes, demonstrating the 'docs' type and 'changelog' scope.

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

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

### Example Git Commit Body with Stacktrace

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

Demonstrates how to include detailed information, such as stack traces or error messages, within the commit body. This practice ensures that critical debugging information is indexed and easily searchable for future reference.

```Git
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>
```

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

### Install GraphQL Client for Dart

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

Instructions to add the `graphql` package as a dependency to a Dart/Flutter project using `flutter pub add` and import it into Dart code.

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

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

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

### Example Git Commit Message: Bug Fix with Body

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

Provides an example of a Git commit message for a bug fix, including a detailed body explaining the dependency update required. This showcases how to provide context beyond the subject line.

```Git
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.
```

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

### Install GraphQL Flutter Package via Pub

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

Adds the `graphql_flutter` package to your Flutter project's `pubspec.yaml` dependencies using the `flutter pub add` command, making it available for use.

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

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

### Project Directory Structure Overview

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

Displays the top-level directory structure of the `graphql-flutter` project, showing the `example`, `lib`, and `test` directories with a depth limit of 3, providing an initial understanding of the project's organization.

```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
```

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

### Generate Changelogs for GraphQL Flutter Packages

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

Utilize `make` commands to automate the generation of changelogs. `changelog_client` targets the `graphql` package, `changelog_flutter` targets `graphql_flutter`, and `changelog` generates for both. Ensure `GITHUB_TOKEN` is set.

```Shell
make {changelog_client|changelog_flutter|changelog}
```

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

### Implement GraphQL Subscription with Flutter Subscription Widget

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

This example shows how to use the `Subscription` widget in a stateful Flutter widget to listen for real-time updates from a GraphQL subscription. It includes handling loading states, exceptions, and accumulating results using the `ResultAccumulator` helper widget.

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

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

### Composing GraphQL Links with Link.from and split

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

This snippet illustrates a comprehensive setup for GraphQL links, showing how to combine common links, split terminating links based on request type (e.g., subscriptions vs. HTTP), and apply specific authentication links. It highlights the importance of `split` for multiple terminating links.

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

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

### Verify Java Version for Android Build

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

Executes a shell command to display the installed Java Development Kit (JDK) version. Java 17 is a prerequisite for building Android applications with this project.

```sh
java -version
```

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

### Set GitHub Personal Access Token

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

Before executing release commands that interact with GitHub, set the `GITHUB_TOKEN` environment variable. This token must have sufficient permissions to create releases and access repository data.

```Shell
export GITHUB_TOKEN="your_token"
```

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

### Using client.fetchMore for Data Pagination in Dart

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

This experimental Dart example demonstrates how to implement `client.fetchMore` to retrieve additional data, such as for pagination, when `watchQuery` is not in use. It illustrates the process of resolving `fetchMore` options based on the `latestResult` and updating the query logic.

```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;
  }
}
```

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

### Execute GraphQL Query using useQuery Hook in Dart

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

Provides an alternative method for executing GraphQL queries using the useQuery hook from the flutter_hooks package. It shows how to retrieve query results and handle different states (loading, error, data) in a more functional, hook-based style, similar to the Query widget example.

```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'] ?? '');
});
```

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

### Using client.watchQuery for Reactive Data Listening

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

`client.watchQuery` allows executing GraphQL queries and mutations while reactively listening to cache changes. This example shows how to set up an `ObservableQuery` to fetch data, handle loading states, exceptions, and process results from the stream.

```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();
```

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

### Define GraphQL Schema with Interfaces and Unions for Normalization

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

Presents a GraphQL schema example featuring an interface (`PersonI`), concrete types (`Employee`, `InStoreCustomer`, `OnlineCustomer`), and a union (`CustomerU`). This schema is used to illustrate the need for a `possibleTypes` map for correct fragment resolution and cache normalization.

```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
```

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

### Trigger GraphQL Pagination with fetchMore() Call

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

This example shows how to trigger the `fetchMore()` function, typically from a UI element like a `RaisedButton`, by passing the pre-configured `FetchMoreOptions` to initiate a new GraphQL operation and fetch additional data for pagination.

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

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

### Define GraphQL Query String in Dart

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

Shows how to define a multi-line GraphQL query string in Dart. This example defines a 'ReadRepositories' query that accepts an integer variable for the number of repositories to fetch, retrieving their ID, name, and star status.

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

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

### Advanced GraphQL Mutation with Cache Update and Optimistic Result

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

This comprehensive example illustrates a `Mutation` widget in Flutter, configuring `MutationOptions` for a GraphQL operation. It details the `update` callback for manual cache manipulation using `cache.writeFragment` to update specific fragments, handles exceptions, and demonstrates passing a pre-calculated `expectedResult` as `optimisticResult` to `toggleStar` for immediate UI feedback.

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

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

### Implement Server-Side WebSocket Authentication Check (TypeScript)

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

Provides a TypeScript example of a server-side `onConnect` handler for `graphql-ws` that validates an authorization token from connection parameters and closes the socket with a custom error code 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;
            }
        },
    },
},
```

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

### Handle OperationException in GraphQL Flutter

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

Illustrates how to check for and handle `OperationException` from a `QueryResult` in Dart. The example demonstrates checking `result.hasException` and then specifically identifying a `NetworkException` within `result.exception.linkException` to implement custom error handling logic.

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

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

### Configure Default Policies for GraphQLClient in Dart

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

Illustrates how to set default policies for the `GraphQLClient` itself using `DefaultPolicies`. This example specifically configures `watchMutation` behavior, allowing watched mutations to behave similarly to watched queries by defining their `FetchPolicy`, `ErrorPolicy`, and `CacheRereadPolicy`.

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

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

### Standard Git Commit Message Format

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

Defines the required structure for Git commit messages in the graphql-flutter project, including mandatory header components (type, scope, subject) and optional body and footer sections. Emphasizes a 100-character line limit for readability and the use of the footer for issue references.

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

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

### Using FragmentRequest for Direct Cache Access in GraphQL Flutter (Dart)

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

This example illustrates how to create a `FragmentRequest` for `readFragment` and `writeFragment` operations. Unlike `Request`, `FragmentRequest` requires `idFields` to identify the corresponding entity in the cache. It also shows the `asRequest` convenience API for `Fragment` objects.

```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);
```

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

### Integrating AWS AppSync with Cognito User Pools

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

This snippet provides an example of how to configure `AuthLink` to work with AWS AppSync GraphQL APIs secured by Cognito User Pools. It shows how to extract the JWT token from a `CognitoUserSession` and pass it to the `AuthLink` for authentication.

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

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

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

### Implement Custom Data ID Generation for Versioned Entities (Dart)

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

Provides an example of a custom `dataIdFromObject` function in Dart. This function demonstrates how to create unique data IDs for entities that include versioning, preventing data clobbering in the cache by incorporating `entityId` and `version` along with `__typename`.

```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}';
}
```

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

### Run Flutter Client for Web Support

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

Launches the Flutter client application in a Chrome browser. This command enables web-based interaction with the GraphQL server.

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

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

### Initialize GraphQLClient with Authentication and Cache

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

Demonstrates how to create a `GraphQLClient` instance in Dart, configuring it with an `HttpLink` for the GraphQL endpoint, an `AuthLink` for token-based authentication, and a `GraphQLCache` for in-memory caching. It also shows how to conditionally add a `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,
);
```

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

### Run Flutter Client on iOS Device

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

Executes the Flutter client application on a connected iOS device. This allows the client to interact with the running GraphQL server.

```bash
flutter run
```

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

### Initialize GraphQLClient with HttpLink and AuthLink in Dart

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

Demonstrates how to set up a GraphQLClient for connecting to a GraphQL server. It uses HttpLink for the endpoint, AuthLink for authentication (e.g., GitHub personal access token), and GraphQLCache with HiveStore for persistent caching.

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

}
```

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

### Implement GraphQL Subscription with Flutter Hooks

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

This snippet provides an alternative, more concise way to implement GraphQL subscriptions using the `useSubscription` hook within a `HooksWidget`. It demonstrates how to manage subscription state, including loading and error handling, in a functional style.

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

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

### Core Module Directory Structure

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

Illustrates the internal structure of the `lib/src/core` module, detailing its key files such as `_base_options.dart`, `query_manager.dart`, and `observable_query.dart`, which contain the main execution path logic for queries, mutations, and subscriptions.

```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
```

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

### GraphQLDataProxy Class API Reference

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

Provides a direct link to the official API documentation for the `GraphQLDataProxy` class, which is essential for direct cache access and manipulation.

```APIDOC
Class: `GraphQLDataProxy`
Purpose: Provides direct cache access API.
External Documentation: https://pub.dev/documentation/graphql/latest/graphql/GraphQLDataProxy-class.html
```

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

### Subscribe to GraphQL Subscription Document

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

Illustrates how to define a GraphQL subscription query and then use the `client.subscribe` method to listen for real-time updates from the server, processing each incoming event.

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

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

### Initialize GraphQL Client with HiveStore Persistence

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

This Dart code snippet demonstrates how to initialize a `GraphQLClient` by integrating `HiveStore` for persistent caching. It shows opening a Hive box at a specified path and passing the resulting store to `GraphQLCache`.

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

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

### Configure GraphQL Link for Subscriptions

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

Demonstrates how to split the GraphQL link chain to route subscription requests specifically to a WebSocket link, ensuring proper handling of real-time data.

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

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

### Initializing GraphQLCache with HiveStore for Persistence

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

Shows how to initialize GraphQLCache with HiveStore to enable disk persistence for the cache. This requires initHiveForFlutter() for Flutter applications and decouples persistence from the cache.

```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()),
)
```

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

### Open iOS Project in Xcode

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/examples/starwars/ios/Runner/Assets.xcassets/LaunchImage.imageset/README.md

Use this shell command to open the iOS Runner project's Xcode workspace. This allows you to access and modify project settings, including the Assets.xcassets catalog for managing launch screen images and other visual assets.

```shell
open ios/Runner.xcworkspace
```

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

### GraphQLCache Class API Reference

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

Provides a direct link to the official API documentation for the `GraphQLCache` class, detailing its methods and properties for managing cached GraphQL data.

```APIDOC
Class: `GraphQLCache`
Purpose: Manages cached GraphQL data.
External Documentation: https://pub.dev/documentation/graphql/latest/graphql/GraphQLCache-class.html
```

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

### Subscribing to GraphQL Events with client.subscribe and Subscription Widget

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

Demonstrates the updated subscription API, showing how to define a GraphQL subscription document using gql() and how to use it with client.subscribe for programmatic subscriptions or the Subscription widget for declarative usage in Flutter.

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

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

### Utilize Other GraphQL Hooks in Flutter

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

This section highlights additional useful hooks provided by the `graphql_flutter` package. These hooks allow direct access to the GraphQL client, watching queries, and watching mutations, simplifying common GraphQL operations in a functional component style.

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

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

### Configuring GraphQL Links with HttpLink, AuthLink, and WebSocketLink

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

Illustrates the new gql_link system for configuring network operations. It shows how to set up HttpLink and AuthLink, and how to conditionally use WebSocketLink for subscriptions by splitting the link chain based on request type.

```dart
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 GraphQL Link for Subscriptions in Dart

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

This snippet demonstrates how to split your GraphQL link configuration to direct subscription requests to a WebSocket link, enabling real-time communication with the server. This is a prerequisite for using GraphQL subscriptions.

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

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

### Open Xcode Workspace for Flutter Project

Source: https://github.com/zino-hofmann/graphql-flutter/blob/main/packages/graphql_flutter/example/ios/Runner/Assets.xcassets/LaunchImage.imageset/README.md

This command opens the Xcode workspace for your Flutter project, which is necessary to access and modify the project's asset catalog, including launch screen images. After opening, navigate to `Runner/Assets.xcassets` to manage your assets.

```Shell
open ios/Runner.xcworkspace
```

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

### Execute GraphQL Query and Process Result

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

This Dart snippet demonstrates how to send a `QueryOptions` object to the `GraphQLClient` using `client.query()`. It also shows how to await the `QueryResult`, check for exceptions, and safely access the returned data, such as a list of repositories.

```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>;

// ...
```

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

### Execute GraphQL Upload Mutation in Dart

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

This Dart code demonstrates how to perform a GraphQL file upload. It shows how to create a `MultipartFile` from a string with specified filename and content type, and then pass it as a variable within `MutationOptions` for execution.

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

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

### Creating Request and QueryOptions for GraphQL Cache Access in Dart

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

This snippet demonstrates how to construct `QueryOptions` and `Request` objects for use with `readQuery` and `writeQuery` methods in GraphQL Flutter. It shows both manual `Request` construction and the experimental `asRequest` convenience API, highlighting their equivalence. These methods are used for direct cache interaction.

```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);
```

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

### Chaining and Routing GraphQL Links

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

This section demonstrates two ways to chain GraphQL links: using `concat` for sequential linking and `Link.from` for combining multiple links into one. It also shows how `Link.split` can route requests conditionally, emphasizing that link order is crucial for correct request processing.

```Dart
/// 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);
```

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

### Registering Flutter Service Worker and Loading Main Application

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

This JavaScript snippet handles the registration of the Flutter service worker (`flutter_service_worker.js`) to enable offline capabilities and efficient caching. It checks for service worker support, registers the worker, waits for its activation, and then loads the main application script (`main.dart.js`). It also includes logic to detect and update new service worker versions and a timeout-based fallback to directly load the script if the service worker fails to activate within a reasonable time.

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

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

### Wrap MaterialApp with GraphQLProvider in Dart

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

Illustrates how to wrap your Flutter application's MaterialApp widget with GraphQLProvider. This makes the configured GraphQLClient available to all descendant Query and Mutation widgets, enabling them to interact with the GraphQL server.

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

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

### Execute GraphQL Mutations with Flutter's useMutation Hook

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

This snippet illustrates the use of the `useMutation` hook in `graphql-flutter` as an alternative to the `Mutation` widget. It demonstrates how to configure the hook with `MutationOptions` for the mutation document, cache updates, and completion callbacks, and how to call `runMutation` on the returned hook object to execute the mutation.

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

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

### Overview of GraphQL Direct Cache Access API

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

Describes the direct cache access API available through `GraphQLCache` and `GraphQLClient`, enabling local state management. It highlights the importance of using `client.writeQuery` and `client.writeFragment` for automatic rebroadcasting, rather than directly manipulating the `client.cache`.

```APIDOC
GraphQLCache:
  - Leverages 'normalize' for Apollo-ish direct cache access.
  - Methods available on cache proxies (GraphQLCache, OptimisticProxy, GraphQLClient).

GraphQLClient:
  - writeQuery(options: WriteQueryOptions): Writes data to the cache for a given query.
  - writeFragment(options: WriteFragmentOptions): Writes data to the cache for a given fragment.

Usage Notes:
  - Prefer 'client.writeQuery' and 'client.writeFragment' over 'client.cache' methods for automatic rebroadcasting.
  - 'GraphQLDataProxy' API docs provide a complete rundown.
```

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

### Create QueryOptions for GraphQL Query

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

This Dart code shows how to construct a `QueryOptions` object for a GraphQL query. It includes converting the query string to an AST document using `gql()` and providing variables, such as `nRepositories`, required by the query.

```Dart
const int nRepositories = 50;

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

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

### Define GraphQL Query for Repositories

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

This Dart snippet illustrates how to define a GraphQL query as a multi-line string. The query, named `ReadRepositories`, accepts an integer variable `$nRepositories` to fetch a specified number of repositories from the viewer's account.

```Dart
const String readRepositories = r'''
  query ReadRepositories($nRepositories: Int!) {
    viewer {
      repositories(last: $nRepositories) {
        nodes {
          __typename
          id
          name
          viewerHasStarred
        }
      }
    }
  }
''';
```

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

### Cache Module Directory Structure

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

Shows the directory layout of the `lib/src/cache` module, highlighting files like `_normalizing_data_proxy.dart`, `_optimistic_transactions.dart`, and `cache.dart`, which are central to the layered optimism system and data normalization.

```bash
tree lib/src/cache
├── _normalizing_data_proxy.dart  # Operation normalization code shared by 
│                                 # GraphQLCache and OptimisticProxy.
├── _optimistic_transactions.dart # OptimisticProxy for optimistic transactions.
├── cache.dart      # Puts it all together and implements "optimistic layers."
├── data_proxy.dart # The abstract GraphQLDataProxy api.
├── fragment.dart   # `gql_exec`-like API for readFragment and writeFragment.
├── hive_store.dart # The recommended store using hive.
└── store.dart      # The Store abstraction.
```

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

### Add Headers to WebSocket Connection with initialPayload

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

Explains how to use the `initialPayload` property to include custom headers, such as authorization tokens, when establishing a WebSocket connection for GraphQL subscriptions.

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

    return headers;
},
```

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

### Import GraphQL Flutter in Dart Code

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

Imports the `graphql_flutter` package into a Dart file, allowing access to its classes and functions for building GraphQL-powered Flutter applications.

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

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

### Customize WebSocket Channel with connect Parameter (Dart)

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

Illustrates the use of the experimental `connect` parameter in `WebSocketLink` to supply a custom `WebSocketChannel`, emphasizing the need to wrap it with `.forGraphQL()` for proper client stream listening.

```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;
}
```

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

### Define GraphQL Query for Repository Data

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

This GraphQL snippet defines a query named `ReadRepositories` that fetches a specified number of repositories (`$nRepositories`) for the current viewer. It retrieves the `id` and `name` of each repository node. This query is used as input for code generation tools.

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

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

### Configure Android Build.gradle for Java 17

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

Adjusts the `android/app/build.gradle` file to set `sourceCompatibility`, `targetCompatibility`, and `jvmTarget` to `JavaVersion.VERSION_17`. This ensures the Android project compiles correctly with Java 17.

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

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

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

### Execute GraphQL Query using Query Widget in Dart

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

Demonstrates how to use the Query widget to execute a GraphQL query within a Flutter widget. It covers setting query options, passing variables, handling loading and error states, and rendering the fetched data in a ListView.

```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'] ?? '');
    });
  },
);
```

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

### GraphQL Flutter Cache API Reference

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

Detailed reference for direct cache access methods and related configurations in GraphQL Flutter.

```APIDOC
Request:
  Description: Represents a GraphQL operation request for the link system.
  Usage: Used with `readQuery` and `writeQuery`.
  Construction:
    - `QueryOptions.asRequest`
    - `Request(operation: Operation(document: gql(...)), variables: {...})`
    - `Operation(document: gql(...)).asRequest(variables: {...})` (convenience)

readQuery(request: Request):
  Description: Reads data from the cache.
  Parameters:
    - `request`: `Request` - The request object defining the query.
  Availability: `GraphQLCache`, `OptimisticProxy`, `client`.

writeQuery(request: Request, data: Map<String, dynamic>):
  Description: Writes data to the cache.
  Parameters:
    - `request`: `Request` - The request object defining the query.
    - `data`: `Map<String, dynamic>` - The data to write.
  Availability: `GraphQLCache`, `OptimisticProxy`, `client`.

FragmentRequest:
  Description: Represents a GraphQL fragment request for cache access.
  Usage: Used with `readFragment` and `writeFragment`.
  Construction:
    - `FragmentRequest(fragment: Fragment(document: gql(...)), idFields: {...})`
    - `Fragment(document: gql(...)).asRequest(idFields: {...})` (convenience)
  Note: Requires `idFields` to locate entities.

readFragment(request: FragmentRequest):
  Description: Reads data from the cache based on a fragment.
  Parameters:
    - `request`: `FragmentRequest` - The fragment request object.
  Availability: `GraphQLCache`, `OptimisticProxy`, `client`.

writeFragment(request: FragmentRequest, data: Map<String, dynamic>):
  Description: Writes data to the cache based on a fragment.
  Parameters:
    - `request`: `FragmentRequest` - The fragment request object.
    - `data`: `Map<String, dynamic>` - The data to write.
  Availability: `GraphQLCache`, `OptimisticProxy`, `client`.

GraphQLCache.partialDataPolicy:
  Description: Configures strictness for data written to the cache.
  Type: `PartialDataCachePolicy`
  Values:
    - `PartialDataCachePolicy.acceptForOptimisticData` (default): Optimistic data excluded from strict constraints.
    - `PartialDataCachePolicy.accept`: No structural constraints enforced.
    - `PartialDataCachePolicy.reject`: Full structural constraints enforced.

Cache Write Exceptions:
  CacheMisconfigurationException:
    Description: Thrown if structure seems correct but fails due to a `typePolicy`.
  UnexpectedResponseStructureException:
    Description: Thrown if the server response looks malformed.
  MismatchedDataStructureException:
    Description: Thrown in the event of a malformed optimistic result (when `PartialDataCachePolicy.reject` is active).
  CacheMissException:
    Description: Thrown if write succeeds but `readQuery` then returns `null` (data will not be overwritten).
```

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

### Create a new Git branch for fixes or features

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

Before making changes, create a new Git branch. For bug fixes, branch from 'master'; for new features, branch from 'beta'.

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

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

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

### Defining GraphQL Mutation for Code Generation

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

This snippet shows a `.graphql` file defining an `AddStar` mutation. This file is used by `graphql_codegen` to generate type-safe Dart code for executing the mutation, improving performance and ensuring type safety.

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