Is the disclaimer for the maskFragments method misleading?

[pmooney-socraticworks]

The disclaimer here states:

You shouldn’t have to use it in your regular component code.

However, I found I had to use it in runtime code in order to update the local cache for my apollo client.

My use case: When a person lands on the page, I perform a query to fetch the "active" entities that belong to that list. The user can toggle between "active" and "archived" lists. When the user navigates to the "archived" list, I query with an "archived" parameter to the query:

const todoFragment = graphql(`
    fragment TodoFragment on Todo {
        id
        archived
        title
    }
`);

const todosQuery = graphql(
    `
        query scenarios($archived: Boolean!) {
            todos(archived: $archived) {
                ...TodoFragment
            }
        }
    `,
    [todoFragment]
);

With fragment masking, these entities are stored as a list of refs within the queries:

// @apollo/client serialized InMemoryCache
todos(archived: true): { todos: [{ _ref: 'Todo:ABC123'}, ...] }
todos(archived: false): { todos: [{ _ref: 'Todo:ABC456'}, ...] }

Which is all fine and dandy. However, the user is able to move these todos back and forth between the list. Rather than refetching the todosQuery after the mutation, I opt to update the local cache to account for this. This is where I have to use maskFragments, since I need to move one fragment from one list to the other.

                updateTodo({
                    variables: { data: { id, archived: true } },
                    update: (cache) => {
                        cache.updateQuery(
                            { query: todosQuery, variables: { archived: false } },
                            (cachedTodos) => ({
                                todos:
                                    cachedTodos?.todos.filter(
                                        (todoRef) => readFragment(todoFragment, todoRef).id !== id
                                    ) ?? [],
                            })
                        );

                        const updatedTodo = cache.readFragment({
                            fragment: todoFragment,
                            id: `Todo:${id}`,
                        });
                        if (!updatedTodo) return;

                        cache.updateQuery(
                            { query: todosQuery, variables: { archived: true } },
                            (cachedTodos) => {
                                if (!cachedTodos) return undefined;
                                return {
                                    todos: [
                                        ...cachedTodos.todos,
                                        maskFragments([todosFragment], updatedTodo), // HERE!
                                    ],
                                };
                            }
                        );
                    },
                });

I am not aware of any other way to generate a fragment mask to update the list of fragment masks in the cache. If there isn't another way, it might be helpful to remove / update the disclaimer to account for these types of use cases, as for someone new to graphql / apollo / gql.tada, this may throw them off as "not the right thing to do"

[kitten]

This is an "Apollo-ism", but when we say:

You shouldn’t have to use it in your regular component code.

We mean that it's unexpected for regular UI code to assemble typed queries with maskFragments.
The update callback in your above example is not UI code and not component code. While Apollo has patterns that embeds these cache updaters in regular UI code, they're strictly speaking not part of any UI-driven components, but instead, cache configuration.

It's also worth noting — and I don't know if Apollo has added more APIs since then — that using the original query to update the cache is not strictly speaking necessary.
In general what I'd expect is:

• update should use the second argument passed to it, rather than surrounding variables that happen to be in scope
• it shouldn't have to use todosQuery but could also use any other query that provides the minimum fields to perform the update (the list selection and the id field)
  So, there's definitely cases where this code doesn't have to use maskFragments as well

[pmooney-socraticworks]

Thanks for getting back to me @kitten, and also supporting an awesome open source project.