Docs
mutationUtils

mutationUtils

A set of helpers for writing Relay mutation updaters without having to manipulate RecordProxy/ConnectionHandler by hand in every common case. Covers:

  • inserting/removing items in linked records lists;
  • inserting/removing edges in paginated connections (@connection);
  • optimistic updaters for connections;
  • copying scalar fields from a JS object to a RecordProxy.

It also exports ClientMutationID, an id generated once per module load to fill the clientMutationId field expected by the Relay Modern pattern.

When to use

✅ Use when…🚫 Avoid when…
  • In mutation updater / optimisticUpdater, to insert/remove items in lists and connections.
  • In optimistic responses, to populate the store with data that hasn't arrived from the server yet.
  • For very specific updates (nested scalar fields, N-N relations with setLinkedRecords), prefer manipulating the store directly — these helpers cover the common cases, not all of them.

Example

import { commitMutation } from '@apollion-dsi/relay';
import { connectionDeleteEdgeUpdater } from '@apollion-dsi/relay/mutationUtils';
 
await commitMutation<DeleteTodoMutation>(Environment, {
  mutation: graphql`...`,
  variables: { id: todoId },
  updater: (store) => {
    connectionDeleteEdgeUpdater({
      parentId: userId,
      connectionName: 'TodoList_todos',
      nodeId: todoId,
      store,
    });
  },
});

Granular imports

import { connectionDeleteEdgeUpdater } from '@apollion-dsi/relay/mutationUtils';
// or via the root barrel
import { connectionDeleteEdgeUpdater } from '@apollion-dsi/relay';

See also

commitMutationRelayArgsInterface