Offix provides first class support for performing GraphQL operations while offline. Mutations are held in a queue that is configured to hold requests while the client is offline. When the client goes offline for long periods of time they will still be able negotiate local updates with the server state thanks to powerful conflict resolution strategies.
Offix-client offers a comprehensive set of features to perform data operations when offline. Thanks to the offline mutation store users can stage their changes to be replicated back to the server when they return online.
Please follow chapters below for more information.
Querying local cache
By default queries are cached based on the type and id field, and the results of performed queries are cached as well and they will be available when the client is offline.
Because of this, when mutations that can change query results are performed, the
refetchQueries or update options of the mutate method should be used to ensure the local cache is kept up to date.
Offix makes your cache simple to manage, with out of the box cache helpers in
offix-cache or by automatically wrapping these helpers in offix-client through the
To use the
offlineMutate function, we first need to create our
MutationHelperOptions object. This is an extension of Apollo's MutationOptions.
We can also provide more than one query to update in the cache by providing an array to the
We then simply pass this object to
offlineMutate and our cache is automatically kept up to date.
If you do not wish to use offline capabilities of offix for some mutations, use the
client.mutate will not react to the changes in the network state. Requests are not enqueued into offline queue.
client.offlineMutate function will return immediately after is called.
Returned promise will resolve into error (
catch method is triggered).
Developers can detect if error is an offline error and watch for change to be replicated back to server.
Note: Additionally to watching individual mutations framework offers global offline listener that can be supplied when creating client.
Global Update Functions
Apollo client holds all mutation parameters in memory. An offline Apollo client will continue to store mutation parameters and once online, it will restore all mutations to memory. Any Update Functions that are supplied to mutations cannot be cached by an Apollo client resulting in the loss of all optimisticResponses after a restart. Update functions supplied to mutations cannot be saved in the cache. As a result, all optimisticResponses will disappear from the application after a restart and it will only reappear when the Apollo client becomes online and successfully syncs with the server.
To prevent the loss of all optimisticResponses after a restart, you can configure the
update functions to restore all optimisticResponses.
Making modifications when offline
Client provides queue that stores mutations performed when offline. By default queue saves data in storage to be available after application restarts. Queue will hold requests until application will come back online.
Developers can adjust how queue will process new mutations by supplying custom
Listening for Events
It is possible to provide
offlineQueueListener in config to be notified about offline related events:
Below is an example
ApolloQueueEntryOperation objects have two top level fields:
qid- Queue ID. This ID is randomly generated and mostly used by the
op- The operation. In
offix-clientIt's of type
MutationOptions, the options object passed into
client.offlineMutatewith some extra metadata set by
Apollo Offline Client strongly leverages Apollo Cache. Please follow documentation for more information about caching in Apollo GraphQL
Querying your data
Cache is used to hold data that can be fetched when client is offline.
To effectively work with cache users can use
when performing queries. This policy will try to use local cache in
situations when cache was already populated with the server side data.
Cache is going to be refueled by subscriptions, pooling or regular queries happening in UI.
Designing your Types
OfflineClient assumes your GraphQL types have always have an
id field. An
id field is also expected from server responses. If your GraphQL types do not use
id as the field name, a custom
id field can be used.
Using Custom id Fields
If your types use a different id field, for example
uuid, take the following steps.
define a dataIdFromObject function for the Apollo Cache.
The Apollo Cache needs to understand how to compose an id for a given object coming from queries and mutations.
By default the ID is composed as
The following type uses
uuid as the id field.
To support this case, a custom
dataIdFromObject field should be passed.
See the Apollo Cache Documentation for more details.
idField in offlineMutate
idField option should be included.