Interfaces: ApolloMutation

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.

Exports

import { ApolloMutationInterface } from '@apollo-elements/interfaces/apollo-mutation';

Properties

awaitRefetchQueries

(optional)

boolean

Queries refetched as part of refetchQueries are handled asynchronously, and are not waited on before the mutation is completed (resolved). Setting this to true will make sure refetched queries are completed before the mutation is considered done. false by default.

called

boolean

Whether the mutation was called

errorPolicy

(optional)

ErrorPolicy

Specifies the ErrorPolicy to be used for this mutation.

fetchPolicy

(optional)

Extract<FetchPolicy, 'no-cache'>

Specifies the FetchPolicy to be used for this mutation.

ignoreResults

(optional)

boolean

If true, the returned data property will not update with the mutation result.

mutation

DocumentNode | TypedDocumentNode

A GraphQL document containing a single mutation. You can set it as a JavaScript property or by appending a GraphQL script to the element (light DOM).

<script type="application/graphql">
  mutation { updateLastSeen }
</script>

optimisticResponse

Data<D> | ((vars: Variables<D, V>) => Data<D>)

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.

element.optimisticResponse = ({ name }: HelloMutationVariables) => ({
  __typename: 'Mutation',
  hello: {
    __typename: 'Greeting',
    name,
  },
});

refetchQueries

RefetchQueriesType<D> | null

A list of query names which will be refetched once this mutation has returned. This is often used if you have a set of queries which may be affected by a mutation and will have to update. Rather than writing a mutation query reducer (i.e. updateQueries) for this, you can refetch the queries that will be affected and achieve a consistent store once these queries return.

client

inherited from ApolloElementInterface

ApolloClient<NormalizedCacheObject> | null

The Apollo Client instance

Defaults to window.__APOLLO_CLIENT__, which is set by default when creating an Apollo Client. That means that in most cases, it's not necessary to explicity set the client property. For more information see Getting Started: Apollo Client.

context

(optional) inherited from ApolloElementInterface

Record<string, unknown>

Context passed to the link execution chain.

data

inherited from ApolloElementInterface

Data<D> | null

Latest mutation data.

document

inherited from ApolloElementInterface

DocumentNode | TypedDocumentNode | null

A GraphQL document containing a single query, mutation, or subscription. You can set it as a JavaScript property or by appending a GraphQL script to the element (light DOM).

static

documentType

inherited from ApolloElementInterface

'mutation'

Hint that this is a mutation component

error

(optional) inherited from ApolloElementInterface

Error | ApolloError | null

Latest error

errors

(optional) inherited from ApolloElementInterface

readonly GraphQLError[] | null

Latest errors.

loading

inherited from ApolloElementInterface

boolean

Whether a request is in-flight.

variables

inherited from ApolloElementInterface

Variables<D, V> | null

An object that maps from the name of a variable as used in the mutation GraphQL document to that variable's value.

Methods

async

mutate

This 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>>>

Optional, partial mutation params

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 \| TypedDocumentNode`	See mutation
optimisticResponse	`OptimisticResponseType<D, V>`	See optimisticResponse
refetchQueries	`RefetchQueriesType<D>`	See refetchQueries
update	`MutationUpdaterFn<Data<D>>`	See updater
variables	`Variables<D, V>`	See variables

Returns

Promise<FetchResult<Data<D>>>

A FetchResult object containing the result of the mutation and some metadata.

Property	Type	Description
data	`Data<D>`	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

onCompleted

(optional)

Callback for when a mutation is completed.

Parameters

data

Data<D>

Returns

void

onError

(optional)

Callback for when an error occurs in mutation.

Parameters

error

Error

Returns

void

updater

(optional)

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.

Note that since this function is intended to be used to update the store, it cannot be used with a no-cache fetch policy. If you're interested in performing some action after a mutation has completed, and you don't need to update the store, use the Promise returned from client.mutate instead.

Parameters

cache

ApolloCache

Use the cache.writeQuery, cache.writeFragment, etc. methods to update the cache following the mutation.

result

FetchResult<Data<D>>

See mutate

Property	Type	Description
data	`Data<D>`	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

Returns

void

protected

documentChanged

(optional) inherited from ApolloElementInterface

Lifecycle callback that reacts to changes in the GraphQL document.

Parameters

document

DocumentNode | TypedDocumentNode | null

The GraphQL document.

Returns

void

protected

variablesChanged

(optional) inherited from ApolloElementInterface

Lifecycle callback that reacts to changes in the operation variables.

Parameters

variables

Variables<D, V> | null

The variables.

Returns

void

Events

Name	Type	Description
apollo-element-connected	`CustomEvent<ApolloElement>`	when the element connects to the DOM
apollo-element-disconnected	`CustomEvent<ApolloElement>`	when the element disconnects from the DOM
apollo-error	`CustomEvent<ApolloError>`	when the mutation rejects
apollo-mutation-result	`CustomEvent<FetchResult<Data<D>>>`	when the mutation resolves

Caught a mistake or want to contribute to the documentation? Edit this page on GitHub!