Mutations
Mutations are executed exactly the same way as queries:
- Create an instance of the generated request class for your Mutation.
- Call
Client.request()
with your request instance. - Listen to the returned Stream.
Creating a Request
Let's assume we've created a CreateReview
Mutation in a file named create_review.graphql
.
In this case, the review depends on ReviewInput
which is defined in our schema:
Running the Ferry generator will create a create_review.req.gql.dart
file with a Class named GCreateReviewReq
. We can instantiate it like this:
Listening to the Request Stream
Now we can execute the mutation and listen for a response like so:
Optimistic Updates
We often want our users to be able to see changes they make within our applications instantly.
To achieve this, we can provide our OperationRequest
with an optimisticResponse
, which will trigger an OperationResponse
that includes the optimistic data immediately. Then, once the network response is received from the server, a second OperationResponse
will be triggered with the network data.
Using the example above, we could include an optimistic response like so:
Updating the Cache
Sometimes we need to update the cache in response to a mutation. Ferry allows arbitrary cache updates following any Operation using UpdateCacheHandler
callbacks, which run whenever an OperationResponse
is received.
The CacheProxy
passed to the handler includes methods to read & write data to & from the cache, including readQuery
, readFragment
, writeQuery
and writeFragment
.
UpdateCacheHandler
Creating an Continuing our example from above, we may want to update our Reviews
Query with the result of executing the CreateReview
Mutation. To do so, we'd write the following UpdateCacheHandler
:
note
Since Dart doesn't yet have algebraic data types, to avoid receiving a type error we must convert our GCreateReviewData
to Json, then convert it back from Json to a GReviewsData_reviews
type before adding it to our reviews list.
Passing Handlers to the Client
In Ferry, the client must be aware of all UpdateCacheHandler
s. This is slightly different from how other GraphQL clients (like Apollo) work, but it's necessary to enable features such as offline mutations.
Now that we've created our createReviewHandler
, we can add it to our Client using the key "createReviewHandler"
, which we'll later use to trigger this handler from our mutation request.
Triggering a Handler
Now we can tell Ferry to trigger our handler when it receives an OperationResponse
for our mutation.
Since our mutation request includes an optimistic response, our handler will first be run as an optimistic patch using the optimistic data. When the network response is received from the server, the optimistic patch will be discarded and the handler will be run again with the response data from the network.
Passing Data to a Handler
If you need to pass any contextual data to your handler, Ferry allows you to include a Json Map in your request.
The data can then be accessed from inside the handler.
caution
If you need offline mutation support, be sure to only include valid Json in the updateCacheHandlerContext
, since this will need to be serialized