OFFLINE_HELPERS.md

Offline Helpers

The SDK provides the following helpers:

• graphqlMutation
• buildSubscription

By default, the helpers look at the GraphQL operation name of the subscription/mutation and modify the cached results of the queries provided by either adding, removing or updating items in the result.

---

graphqlMutation

Import

import { graphqlMutation } from 'aws-appsync-react';

Signature

graphqlMutation(
    mutation: DocumentNode,
    cacheUpdateQuery: CacheUpdatesOptions,
    typename: string,
    idField?: string,
    operationType?: CacheOperationTypes
): React.Component

Parameters

• mutation: DocumentNode - A DocumentNode for the GraphQL mutation
• cacheUpdateQuery: CacheUpdatesOptions - The queries for which the result needs to be updated
• typename: string - Type name of the result of your mutation (__typename from your GraphQL schema)
• (Optional) idField: string - Name of the field used to uniquely identify your records
• (Optional) operationType: CacheOperationTypes - One of 'auto', 'add', 'remove', 'update'.
• Returns React.Component - A react HOC with a prop named after the graphql mutation (e.g. this.props.addTodo)

---

buildSubscription

Builds a SubscribeToMoreOptions object ready to be used by Apollo's subscribeToMore() to automatically update the query result in the cache according to the cacheUpdateQuery parameter

Import

import { buildSubscription } from 'aws-appsync';

Signature

buildSubscription(
    subscriptionQuery: CacheUpdateQuery,
    cacheUpdateQuery: CacheUpdateQuery,
    idField?: string,
    operationType?: CacheOperationTypes
): SubscribeToMoreOptions

Parameters

• subscriptionQuery: CacheUpdateQuery - The GraphQL subscription DocumentNode or CacheUpdateQuery
• cacheUpdateQuery: CacheUpdateQuery - The query for which the result needs to be updated
• (Optional) idField: string
• (Optional) operationType: CacheOperationTypes - One of 'auto', 'add', 'remove', 'update'.
• Returns SubscribeToMoreOptions - Object expected by subscribeToMore()

---

Actions and their list of prefixes when using CacheOperationTypes.AUTO

add	remove	update
create	delete	update
created	deleted	updated
put	discard	upsert
set	discarded	upserted
add	erase	edit
added	erased	edited
new	remove	modify
insert	removed	modified
inserted

---

Examples

Different ways CacheUpdatesOptions can be provided

* (All lines are equivalent)

// Passing a DocumentNode
graphqlMutation(NewTodo, ListTodos);

// Passing a QueryWithVariables
graphqlMutation(NewTodo, { query: ListTodos });

// Passing an array of DocumentNode
graphqlMutation(NewTodo, [ListTodos]);

// Passing an array of QueryWithVariables
graphqlMutation(NewTodo, [{ query: ListTodos, variables: {} }]);

// Passing an object
graphqlMutation(NewTodo, { auto: [ListTodos] });

// Passing a function that returns an object
graphqlMutation(NewTodo, (vars) => {
  return { auto: [ListTodos] };
});

---

Types reference

enum CacheOperationTypes {
  AUTO = 'auto',
  ADD = 'add',
  REMOVE = 'remove',
  UPDATE = 'update',
}

type CacheUpdatesOptions = (
  variables?: object
) => CacheUpdatesDefinitions | CacheUpdatesDefinitions;

type CacheUpdatesDefinitions = {
  [key in CacheOperationTypes]?: CacheUpdateQuery | CacheUpdateQuery[];
};

type CacheUpdateQuery = QueryWithVariables | DocumentNode; // DocumentNode is an object return by the gql`` function

type QueryWithVariables = {
  query: DocumentNode;
  variables?: object;
};