Optimistic updates for Relay Connections

[Kingdutch]

I have a Conversation type with a messages field that is typed ConversationMessagesConnection which in turn contains pageInfo, nodes, and edges (implementing the Relay specification). Graphcache is set-up to use relayPagination for the field. I'm trying to set-up the Graphcache with optimistic updates, but I'm unsure about my data requirements from a mutation.

I understand how I can manipulate the cache in optimistic or update methods on the cache. I could create a placeholder value for the cursor, but I'm worried this might cause invalid queries to the back-end in some cases (although I read it doesn't update with pending mutations).

Additionally, when my mutations returns a Message entity (which is the node in the ConversationMessageEdge used by the connection) then I still wouldn't have a cursor. I could change the mutation to return different/additional data, but I'm not sure what I'd need. Additionally, cursors are dependent on the sorting key for the list they're in to ensure they still work when data is deleted/updated.

Previous discussions that I could find here dealt mostly with simple pagination lists rather than Relay spec based pagination. Any help is appreciated :D

EDIT to add keywords for future searchers: The same questions above could be applied to results for a subscription that needs to update a list using Relay pagination. I suspect the solution to both problems is (nearly) the same.

[kitten]

I could create a placeholder value for the cursor

I believe it may be better not to update the cursor or pageInfo at all. What has previously worked for others and in Relay for instance, afaik, is to append only the edge or item to the last page (or any appropriate one). All queries regarding the optimistic update will be blocked anyway while the mutation is ongoing, so there's no risk of "losing" the added optimistic item, and there's also no point of optimistically updating the cursor. In fact, since optimistic in the best case scenario only returns data and doesn't use cache updates directly and updates adds the new item to a list (regardless of whether it's optimistic or not) this should be indifferent logic in either case.

Additionally, cursors are dependent on the sorting key for the list they're in to ensure they still work when data is deleted/updated.

So on this point and the last, cursors are basically state that is passed back to the server. Because optimistic data never passes back to the server it won't need to update. The only thing you have to be concerned about is when it's possible to pass invalid cursors to the server. So the right thing is not to alter the cursor just because you don't want to queue up another query with an optimistically (read: client-side) created cursor. This is also not an issue because even if your cursor is off by one or two added items, those items will still be returned by the query either way when that next page is fetched.

So the thing here to remember is:

• From your end: Make sure not to trigger queries/mutations with variables that you created optimistically (which never becomes an issue unless you specifically pass "optimistically created IDs" to GraphQL)
• Adding things to a Relay-paginated list is always solid because even when the cursor is "behind" that actually gives refetches and subsequent pages a chance to see the added items again
• The relayPagination helper does deduplication, so even if it sees the items multiple times (e.g. you added it to the current list in the update after a mutation completed, so non-optimistic, and the next page contains it again) it will only show once
• Queries that can override optimistic updates are blocked from being sent. Graphcache has strong protections against optimistic updates accidentally becoming "committed" and against them disappearing unexpectedly.

[Kingdutch]

Eureka

Okay, whew that took me a time to figure out. However, I've learned the following, which I didn't quite understand from the documentation.

Although the cache.inspectFields works on partial entities, it does not return a result if there could be more than a single entity that matches. It will only return results if it can match to a specific entity of concrete types.

The example in the documentation is somewhat misleading because it uses Query as type, which is probably the only of three types (Query, Mutation, Subscription) that doesn't require an ID.

Take the following 7 inspectField examples that I've found as example. The queries executed in the application (leaf and id/__typename fields omitted, but present) when the code is executed in a updates.mutation.sendUserMessage function on the cache are as follows: first a query for currentUser { conversations(last: 10) { messages(last: 1) { ... } } }, then a query for conversation(id: ...) { messages(last: 20) { user: sender { ....} ... } }, then the mutation.

console.log(cache.inspectFields({ __typename: 'Query' }));  // 1
console.log(cache.inspectFields({ __typename: 'User' }));  // 2
console.log(cache.inspectFields({ __typename: 'Conversation' })); // 3
console.log(cache.inspectFields({ __typename: 'Conversation', id: args.input.conversation }));  // 4
console.log(cache.inspectFields({ __typename: 'PrivateConversation' });  // 5
console.log(cache.inspectFields({ __typename: 'PrivateConversation', id: args.input.conversation  })); // 6
console.log(cache.inspectFields({ __typename: 'Message' })); // 7

inspectField 1 returns an array with 2 fields (currentUser and conversation(id: ...)). inspectField 2, 3, 4, 5, 7 all return an empty array. Only inspectField 6 gave me the output that I was looking for that included the two usages of the messages field independent of their arguments, allowing me to implement robust update logic.

It wasn't clear for me from reading the example that I had to find a specific entity, not just all entities of a type. That distinction only clicked when I re-read the first line of the API docs for an uncounted time. Although the example there also still uses Query which made it initially unclear (since my mind never treated the result of Query as a single entity, although of course, it is).

With what I know now, almost all of this makes sense. My troubles were exacerbated slightly by the fact that I had tried inspectField 4 but never tried inspectField 6. I did not know that inspectField had to be called on a concrete type, even though the field I'm interested in is part of the Conversation interface, so it'd be present for all implemented types.

Proposed documentation change

Perhaps we can amend the example in the documentation in some way to drive home the fact that you're always looking for a single entity and amend the API docs to not use Query but a different type for its example, to help enforce the first line of that section of the documentation.

Requested feature change

Could the inspectField method be made to work with interfaces as the type (when schema awareness is enabled, which is the case in my trials).

If that's not possible due to a technical limitation, perhaps we can add that to the docs too.

---

Thanks for all the information! I hope my journey and gained insights can save someone else a few days of trial and error ^^

[kitten]

Just as a tip 😅 try to keep your writing shorter. You can assume that readers have prior knowledge especially, since core contributors are the only ones likely to read in detail up until here 😀

Anyway, we can make sure that the guide is fixed up. I believe I'll just change this line:

and is able to return all fields that the cache has seen on a given type.

It doesn't use the usual phrasing, I.e. "entity", and is hence confusing.

[Kingdutch]

Okay I do run into another hurdle now that I have the fields that I want to update.

The data requested on the fields is different so the data in the cache may be different too. I can't seem to find a reliable query to update both returned fields:

[
  {
    "fieldKey": "messages({\"last\":1})",
    "fieldName": "messages",
    "arguments": {
      "last": 1
    }
  },
  {
    "fieldKey": "messages({\"last\":20})",
    "fieldName": "messages",
    "arguments": {
      "last": 20
    }
  }
]

If I use my original query MessageUpdateQuery it'll work for the last 20 field but the returned data will be null for last: 1 because the latter query initially doesn't need as much data, so not all requested fields are present.

If I request only the message id for both instances, then I get a result in both cases but it seems that I wipe out the cache for the other messages that are returned by the updateQuery, since I'm returning an object with far fewer fields, for all entities except for the new one.

I don't see a way to properly request the fields that were included in the query for the field. Even using more recursive inspectFields and resolve queries is problematic because I wouldn't be able to distinguish between a field value and an entity relationship.

This is the problematic code that'll either throw away a lot of message data if executed only for last: 20 or will seemingly trash the cache in case of last: 1 returning no data for the subsequent last: 20 query.

messageQueries.forEach(({ arguments: fieldArgs }) => {
            console.log(args.input.conversation, fieldArgs);

            cache.updateQuery({
              query: `query ($id: ID!, $last: Int!) {
                conversation(id: $id) {
                  messages(last: $last) {
                    nodes {
                      id
                    }
                  }
                }
              }`,
              variables: {
                id: args.input.conversation,
                last: fieldArgs.last,
              }
            }, data => {
              console.log(data);
              // TODO: implement support for edges
              // If there were no results previously then we have to initialise a new connection.
              if (data.conversation.messages.nodes === null) {
                data.conversation.messages.nodes = [];
              }
              // In case it's the `last: 1` we replace it since the query is only expecting one result.
              if (fieldArgs.last === 1) {
                data.conversation.messages.nodes[0] = message;
              }
              // Otherwise we append the new message in our cache.
              else {
                data.conversation.messages.nodes.push(message);
              }

              return data;
            });
          });

[kitten]

You'll want to append the message to each ending list that doesn't have a before cursor then and not replace any nodes. The length won't matter as long as your UI just display them, especially since the lists will be merged by relayPagination

[Kingdutch]

Just as a tip 😅 try to keep your writing shorter. You can assume that readers have prior knowledge especially, since core contributors are the only ones likely to read in detail up until here 😀

Fair enough, I'm just trying to make sure that it's clear what I'm doing (and making sure that if I, as non-contributor) come back in 3 months I can also still figure it out 😊 I'll try to tighten up my writing here and leave the longer writings for blog posts.

You'll want to append the message to each ending list that doesn't have a before cursor then and not replace any nodes. The length won't matter as long as your UI just display them, especially since the lists will be merged by relayPagination

Okay, that's what my last snippet did. However, it turned out that because my updateQuery didn't request the conversation.id field the cache wasn't able to reconcile the results. I managed to find the warning for that and it looks like everything is now working as expected! 🎉