#Offline GraphQL: the easy parts

Note: Tech talk is a section within the Dutchie Blog where Dutchie Engineers share their experiences with other tech enthusiasts.

---

Picture this: Your app is perfect. It's fast. It's pretty. It overwhelms the GraphQL server with requests. The UX is really really good. Your CI is perfect. When there's no internet, it's unusable. It has 4.9 stars on the App Store. Your app is almost perfect.

Make your app perfect and cache your data on the client. Tear-free.

‍

Reintroducing Brick
‍

Brick runs your data. The easiest way to think of Brick is in terms of pizza, with data as your ingredients.

‍

* You're in a rush and you just need a slice. You buy one from under the heat lamp. This is memory-cached data.

* You're cooking for a small group and a frozen pie is good enough. This is disk-cached data.

* You want to sit down for a nice meal with the freshest ingredients. This is remote-fetched data.

‍

Brick, can do a lot. But we're here to tell you the good news about fetching the same data from GraphQL, memory, and SQLite.

‍

Let's start with the basics.

Querying in Brick

```dartfinal repository = OfflineFirstWithGraphqlRepository()

‍

‍

Queries can be general:

final users = await repository.get();

‍

Or specific:

‍

Or associated:

‍

That's it. That's how you request data from every pizza source. No switching of memory/remote/disk: it's a single entrypoint.

‍

Runtime Document Generation

‍

While most packages utilize code generation to create GraphQL documents, Brick takes advantage of Dart's strong typing. Your source of truth is your Dart class (which ultimately creates a serialize/deserialize adapter.

‍

This permits the return type to be consistent when being used instead of a new class for every return. By leaving the declaration in Brick, the same source of truth is used to generate and manage SQLite columns.

‍

Request this field as a different name

‍

Don't request this field but send it when creating/updating

‍

Don't request or send this field

‍

Customize parsing of GraphQL; useful for differences in language conventions

‍

Document generation can be controller in rare instances where Brick cannot detect the subfields of a field type

‍

Brick's approach is not without pitfalls. Queries are generally unoptimized - you're always requesting the same data as you would with REST. We found that managing separate-but-very-similar return types was not worth the minimal optimization versus making the same request.

That said, if your requests vary significantly for large models, consider creating two models (e.g. `CustomerLight` and a `Customer`) to use the same structure but with smaller requests.

:bulb: Some `upsert` requests (or mutation operations) are much simpler than sending an entire model. These require variables to be declared, and Brick does not presently support generating strongly-typed input classes. Instead, a basic, JS-like `Map<String, dynamic>` can be sent with `Query`.

‍

Decipherable Requests

Operations chill alongside business logic. When a GraphQL request is made, Brick will intelligently create the document and use the declared operation from your configuration:

```dart

class UserQueryOperationTransformer extends GraphqlQueryOperationTransformer {

  GraphqlOperation get get => GraphqlOperation(

    document: r'''query Users {

      getUsers {}

    }'''

  );

  const UserQueryOperationTransformer(super.query, super.instance);

}

@ConnectOfflineFirstWithGraphql(

  graphqlConfig: GraphqlSerializable(

    queryOperationTransformer: UserQueryOperationTransformer.new,

  )

)

class User extends OfflineFirstWithGraphqlModel {}

‍

Streams!

GraphQL subscriptions work, youbetcha. Why wait for your data when you could render it immediately?

```dart

final subscription = repository.subscribe().listen((users) {});

‍

In Flutter:

StreamBuilder>(

  stream: repository.subscribe(),

  builder: (_, snap) => Column(children: snap.data.map(Text.new).toList()),

)

```

Even if your GraphQL server doesn't utilize susbcriptions, you can still use `subscribe`. Events will be triggered every time data is inserted into the local SQLite database.

:warning: Always dispose your streams.

‍

Now Make it Offline

Brick follows an optimistic offline-first practice: data is inserted locally before it reaches the server. If the data doesn't exist, Brick requests it from your GraphQL server:

_It says REST, but it's the same architecture for GraphQL_

‍

Remember, Brick does all of this for you via the single entrypoint. There's no toggling between different data sources in your implementation code.

‍

Retry Queue

If the app is offline when a mutation operation is made, the operation is added to a queue. The queue will reattempt until it receives a successful response from the server. And it will try. And try. And try. We've seen queues retry for 30 days.

_Not your jam? Synchronous execution can be requested (circumventing the queue) by applying the `OfflineFirstUpsertPolicy.awaitRemote` policy._

‍

:bulb: You can still use the retry queue as an independent link in your `gql` client. You can also grab requests about to be retried and delete them if they're perpetually blocking the queue.

‍

---

‍

Lost? Inspired? Hungry? Open an issue with us. We'd love to hear from you.

‍

‍