Mutations are executed exactly the same way as queries:
- Create an instance of the generated request class for your Mutation.
Client.request()with your request.
- Listen to the returned Stream.
Creating a Request
Let's assume we've created a
CreateReview Mutation in a file named
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:
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.
CacheProxy passed to the handler includes methods to read & write data to & from the cache, including
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
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
If Ferry, the client must be aware of all
UpdateCacheHandlers. 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.
If you need offline mutation support, be sure to only include valid Json in the
updateCacheHandlerContext, since this will need to be serialized