Mutation components affect your app’s state by issuing mutations to the GraphQL server. Manage your cache by implementing an updater function, and provide the perception of performance with Optimistic UI.
Mutation components inherit the ApolloElementInterface.
Common interface for mutation elements
See ApolloElementInterface
for more information on events
Properties
documentType
static(read-only)'document'|'query'|'mutation'|'subscription'
controller
publicApolloController<D, V>
data
publicData<D> | null
variables
publicVariables<D, V> | null
awaitRefetchQueries
publicboolean | undefined
called
public(read-only)boolean
fetchPolicy
publicstring | undefined
ignoreResults
publicboolean
mutation
publicComponentDocument<D, V> | null
optimisticResponse
publicOptimisticResponseType<D, V> | undefined
An object that represents the result of this mutation that will be optimistically stored before the server has actually returned a result.
This is most often used for optimistic UI, where we want to be able to see the result of a mutation immediately, and update the UI later if any errors appear.
refetchQueries
publicRefetchQueriesType<D> | null
updateQueries
) for this,
you can refetch the queries that will be affected
and achieve a consistent store once these queries return.client
publicApolloClient | null
document
publicComponentDocument<D, V> | null
graphql-tag
.error
publicError | null
errors
publicreadonly GraphQLError[]
loading
publicboolean
context
publicRecord<string, unknown> | undefined
errorPolicy
publicErrorPolicy | undefined
Much like fetchPolicy
, errorPolicy
allows you to control how GraphQL errors
from the server are sent to your UI code. By default, the error policy treats any
GraphQL Errors as network errors and ends the request chain.
It doesn’t save any data in the cache, and renders your UI with the error property
set to an ApolloError
. By changing this policy per request, you can adjust how
GraphQL Errors are managed by your UI. The possible options for errorPolicy
are:
none
(default): any errors from the request are treated like runtime errors and the observable is stopped (XXX this is default to lower breaking changes going from AC 1.0 => 2.0)ignore
: errors from the request do not stop the observable, but also don’t callnext
all
: errors are treated like data and will notify observables
readyToReceiveDocument
publicboolean
Methods
onCompleted
publicCallback for when a mutation is completed.Parameters
_data
Data<D>
Returns
void
onError
publicCallback for when an error occurs in mutation.Parameters
_error
Error
Returns
void
updater
publicA function which updates the apollo cache when the query responds. This function will be called twice over the lifecycle of a mutation. Once at the very beginning if an optimisticResponse was provided. The writes created from the optimistic data will be rolled back before the second time this function is called which is when the mutation has succesfully resolved. At that point update will be called with the actual mutation result and those writes will not be rolled back.
The reason a DataProxy is provided instead of the user calling the methods directly on ApolloClient is that all of the writes are batched together at the end of the update, and it allows for writes generated by optimistic data to be rolled back.
Examples
updater(cache, result) {
cache.writeQuery({
query: MyProfileQuery,
data: { profile: result.data.updateMyProfile },
});
}
Parameters
params
any[]
Returns
any
mutate
publicThis resolves a single mutation according to the options specified and returns a Promise which is either resolved with the resulting data or rejected with an error.Parameters
params
Partial<MutationOptions<Data<D>, Variables<D, V>>>
All named arguments to mutate default to the element’s corresponding instance property. So you can call element.mutate()
without arguments and it will call using element.mutation
, element.variables
, etc. You can likewise override instance properties per-call by passing them in, e.g.
await element.mutate({
fetchPolicy: 'network-only'
variables: {
...element.variables,
name: 'overridden',
},
});
Property | Type | Description |
---|---|---|
awaitRefetchQueries | boolean |
See awaitRefetchQueries |
context | Record<string, unknown> |
See context |
errorPolicy | ErrorPolicy |
See errorPolicy |
fetchPolicy | FetchPolicy |
See fetchPolicy |
mutation | DocumentNode |
See mutation |
optimisticResponse | OptimisticResponseType<D, V> |
See optimisticResponse |
refetchQueries | RefetchQueriesType<D, V> |
See refetchQueries |
update | MutationUpdaterFn<Data<D>, Variables<D, V>> |
See updater |
variables | Variables<D, V> |
See variables |
Returns
Promise<FetchResult<Data<D>>>
Property | Type | Description |
---|---|---|
data | Data<D, V> |
The result of a successful execution of the mutation |
errors | readonly GraphQLError[] |
included when any errors occurred as a non-empty array |
extensions | boolean |
Reserved for adding non-standard properties |
context | Record<string, unknown> |
See context |
Events
apollo-mutation-result
CustomEvent<FetchResult<Data<D>>>
The mutation resolvedapollo-error
CustomEvent<ApolloError>
The mutation rejectedapollo-element-connected
ApolloElementEvent
The element connected to the DOMapollo-element-disconnected
ApolloElementEvent
The element disconnected from the DOM
Private Methods
documentChanged
protectedLifecycle callback that reacts to changes in the GraphQL documentParameters
document
ComponentDocument<D, V> | null
Returns
void
variablesChanged
protectedLifecycle callback that reacts to changes in the operation variablesParameters
variables
Variables<D, V> | null
Returns
void
Exports
js CustomElement
from types.js
js ControllerHost
from types.js
js ApolloElementElement
from types.js
js ApolloMutationElement
from types.js
js ApolloQueryElement
from types.js
js ApolloSubscriptionElement
from types.js
js GraphQLError
from types.js