Components: apollo-mutation

Provides a way to declare mutations and their variables, including input components.

Inherits from ApolloMutationInterface

Live Demo

<script type="module" src="components.js"></script>
<apollo-client uri="https://api.spacex.land/graphql">
  <apollo-mutation refetch-queries="LatestUsers">
    <script type="application/graphql" src="InsertUser.mutation.graphql"></script>
    <template>
      <link rel="stylesheet" href="InsertUser.css"/>
      <p-card>
        <h2 slot="heading">Add a User</h2>
        <p>Complete the form to add a user.</p>

        <p ?hidden="{{ !data }}">{{ data.insert_users.returning[0].name }} added!</p>

        <slot slot="actions"></slot>
      </p-card>
    </template>

    <mwc-textfield data-variable="name" label="User name" outlined></mwc-textfield>
    <mwc-button trigger label="Add user"></mwc-button>
  </apollo-mutation>
</apollo-client>

Simple Mutation component that takes a button or link-wrapped button as it's trigger. When loading, it disables the button. On error, it toasts a snackbar with the error message. You can pass a variables object property, or if all your variables properties are strings, you can use the element's data attributes

See ApolloMutationInterface for more information on events

Examples

Using data attributes

<apollo-mutation data-type="Type" data-action="ACTION">
  <mwc-button trigger>OK</mwc-button>
</apollo-mutation>

Will mutate with the following as variables:

{
  "type": "Type",
  "action": "ACTION"
}

Using data attributes and variables

<apollo-mutation data-type="Quote" data-action="FLUB">
  <mwc-button trigger label="OK"></mwc-button>
  <mwc-textfield
      data-variable="name"
      value="Neil"
      label="Name"></mwc-textfield>
  <mwc-textarea
      data-variable="comment"
      value="That's one small step..."
      label="comment"></mwc-textarea>
</apollo-mutation>

Will mutate with the following as variables:

{
  "name": "Neil",
  "comment": "That's one small step...",
  "type": "Quote",
  "action": "FLUB"
}

Using variable-for inputs

<label>Comment <input variable-for="comment-mutation" value="Hey!"></label>
<button trigger-for="comment-mutation">OK</button>
<apollo-mutation id="comment-mutation"></apollo-mutation>

Will mutate with the following as variables:

{ "comment": "Hey!" }

Using data attributes and variables with input property

<apollo-mutation data-type="Type" data-action="ACTION" input-key="actionInput">
  <mwc-button trigger label="OK"></mwc-button>
  <mwc-textfield
      data-variable="comment"
      value="Hey!"
      label="comment"></mwc-textfield>
</apollo-mutation>

Will mutate with the following as variables:

{
  "actionInput": {
    "comment": "Hey!",
    "type": "Type",
    "action": "ACTION"
  }
}

Using DOM properties

<apollo-mutation id="mutation">
  <mwc-button trigger label="OK"></mwc-button>
</apollo-mutation>
<script>
  document.getElementById('mutation').mutation = SomeMutation;
  document.getElementById('mutation').variables = {
    type: "Type",
    action: "ACTION"
  };
</script>

Will mutate with the following as variables:

{
  "type": "Type",
  "action": "ACTION"
}

Attributes

'no-shadow'

inherited from StampinoRender

Boolean|string

When set, the element will render to a <div> in its light DOM. If set with a string, the string will be the div's class name.

Properties

static

is

(read-only)

'apollo-mutation'

refetchQueries

refetch-queries

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.

optimisticResponse

OptimisticResponseType<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, or a unary function that takes the mutation's variables and returns such an object.

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.

Examples

Using a function

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

mutation

null | ComponentDocument<D, V>

The mutation.

inputKey

input-key

string|null

key to wrap variables in e.g. input.

When set, variable data attributes will be packed into an object property with the name of this property

Examples

Using the input-key attribute

<apollo-mutation id="a" data-variable="var"></apollo-mutation>
<apollo-mutation id="b" input-key="input" data-variable="var"></apollo-mutation>
<script>
  console.log(a.variables) // { variable: 'var' }
  console.log(b.variables) // { input: { variable: 'var' } }
</script>

ignoreResults

ignore-results

boolean

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

fetchPolicy

fetch-policy

'no-cache' | undefined

Specifies the FetchPolicy to be used for this mutation.

errorPolicy

error-policy

ErrorPolicy | undefined

Specifies the ErrorPolicy to be used for this mutation.

debounce

number | null

Optional number of milliseconds to wait between calls

context

Record<string, unknown> | undefined

Context passed to the link execution chain.

called

boolean

Whether the mutation was called

awaitRefetchQueries

await-refetch-queries

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.

client

inherited from ApolloElement

ApolloClient<NormalizedCacheObject> | null

The Apollo Client instance.

controller

inherited from ApolloElement

ApolloController<D, V>

data

inherited from ApolloElement

Data<D> | null

Latest Data.

document

inherited from ApolloElement

ComponentDocument<D, V> | null

Operation document. GraphQL operation document i.e. query, subscription, or mutation. Must be a parsed GraphQL DocumentNode

error

inherited from ApolloElement

Error | ApolloError | null

Latest error

errors

inherited from ApolloElement

readonly GraphQLError[]

Latest errors

loading

inherited from ApolloElement loading

boolean

Whether a request is in flight.

readyToReceiveDocument

inherited from ApolloElement

boolean

template

(read-only) inherited from StampinoRender template

HTMLTemplateElement | null

Template element to render. Can either be a light-DOM child of the element, or referenced by ID with the template attribute.

Templates are stampino templates using jexpr

templateHandlers

inherited from StampinoRender

TemplateHandlers

variables

inherited from ApolloElement

Variables<D, V> | null

Mutation variables.

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

Methods

public

updater

A 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.

Parameters

params

Parameters<MutationUpdaterFn<Data<D>, Variables<D, V>>>

Returns

ReturnType<MutationUpdaterFn<Data<D>, Variables<D, V>>>

resolveURL

Define this function to determine the URL to navigate to after a mutation. Function can be synchronous or async. If this function is not defined, will navigate to the href property of the link trigger.

Examples

Navigate to a post's page after creating it

<apollo-mutation id="mutation">
  <script type="application/graphql">
    mutation CreatePostMutation($title: String, $content: String) {
      createPost(title: $title, content: $content) {
        slug
      }
    }
  </script>
  <mwc-textfield label="Post title" data-variable="title"></mwc-textfield>
  <mwc-textarea label="Post Content" data-variable="content"></mwc-textarea>
</apollo-mutation>

<script>
  document.getElementById('mutation').resolveURL =
    data => `/posts/${data.createPost.slug}/`;
</script>

Parameters

data

Data<D>

mutation data

trigger

HTMLElement

the trigger element which triggered this mutation

Returns

public

mutate

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

public

$

inherited from StampinoRender

querySelector within the render root.

Parameters

sel

string

Returns

E | null

public

$$

inherited from StampinoRender

querySelectorAll within the render root.

Parameters

sel

string

Returns

NodeListOf<E>

Slots

default slot

Mutations typically trigger when clicking a button. Slot in an element with a trigger attribute to assign it as the element's trigger. The triggering element. Must be a button or and anchor that wraps a button. You may also slot in input elements with the data-variable="variableName" attribute. It's value property gets the value for the corresponding variable.

Events

Name	Type	Description
will-navigate	`WillNavigateEvent`	The mutation resolved and the element is about to navigate. cancel the event to handle navigation yourself e.g. using a client-side router. . `detail` is `{ data: Data, element: this }`
will-mutate	`WillMutateEvent`	The element is about to mutate. Useful for setting variables. Prevent default to prevent mutation. Detail is `{ element: this }`
mutation-error	`MutationErrorEvent`	The mutation rejected. `detail` is `{ error: ApolloError, element: this }`
mutation-completed	`MutationCompletedEvent`	The mutation resolves. `detail` is `{ data: Data, element: this }`
apollo-element-disconnected	`ApolloElementEvent`	The element disconnected from the DOM
apollo-element-connected	`ApolloElementEvent`	The element connected to the DOM
	`WillMutateEvent`

Private API

Private Properties

protected

triggers

(read-only)

Element[]

Slotted trigger nodes

protected

inputs

(read-only)

InputLikeElement[]

Variable input nodes

private

inFlightTrigger

HTMLElement | null

private

doMutate

private

debouncedMutate

protected

buttons

(read-only)

ButtonLikeElement[]

If the slotted trigger node is a button, the trigger If the slotted trigger node is a link with a button as it's first child, the button

private

#root

(read-only)

ShadowRoot | Document | DocumentFragment | null

private

#listeners

private

#buttonMO

MutationObserver | undefined

Private Methods

private

toVariables

Parameters

acc

element

InputLikeElement

Returns

private

isTriggerNode

Parameters

node

Node

Returns

node is HTMLElement

private

isLink

Parameters

node

Element|null

Returns

node is HTMLAnchorElement

private

isButton

False when the element is a link.

Parameters

node

Element|null

Returns

node is ButtonLikeElement

private

debounce

Parameters

f

() => void

timeout

number

Returns

() => void

private

isQueryable

inherited from StampinoRender

Parameters

node

Node

Returns

node is (ShadowRoot|Document)

private async

willNavigate

Parameters

data

Data<D>|null|undefined

triggeringElement

HTMLElement

Returns

Promise<void>

private

willMutate

Parameters

trigger

HTMLElement

Returns

void

private

onTriggerEvent

Parameters

event

Event

Returns

void

private

onSlotchange

Returns

void

private

onLightDomMutation

Parameters

records

MutationRecord[]

protected

getVariablesFromInputs

Constructs a variables object from the element's data-attributes and any slotted variable inputs.

Returns

Variables<D, V> | null

private

didMutate

Returns

void

private

addTriggerListener

Parameters

element

Element

protected

createRenderRoot

inherited from StampinoRender

Returns

ShadowRoot|HTMLElement

private

getElementByIdFromRoot

inherited from StampinoRender

Parameters

id

string|null

Returns

HTMLElement | null

private

getTemplateFromRoot

inherited from StampinoRender

Returns

HTMLTemplateElement | null

Exports

import '@apollo-elements/components/apollo-mutation';
import { ApolloMutationElement } from '@apollo-elements/components/apollo-mutation';