Cache do Apollo: normalização e atualizações

O InMemoryCache armazena cada objeto por meio de uma chave de cache composta por __typename e id: User:1, Post:42. Quando uma consulta retorna um User com id "1", ele é armazenado uma única vez sob essa chave, independentemente de quantas consultas diferentes o incluam.

Qualquer consulta posterior que busque o mesmo User:1 lê a partir da única entrada do cache, garantindo que todos os componentes vejam os mesmos dados.

Quando uma mutação retorna um objeto User:1 atualizado, o Apollo o grava na entrada de cache User:1. Toda consulta ativa que incluía User:1 reflete automaticamente os campos atualizados na interface, sem nenhum código adicional.

Essa propagação automática é a principal vantagem de um cache normalizado em relação a um cache de documento (indexado por consulta).

Leia o resultado atual armazenado em cache de uma consulta: cache.readQuery({ query: GET_USERS }) retorna o objeto de dados como se useQuery o tivesse retornado. Retorna null se a consulta não estiver no cache.

Use readQuery dentro de funções de atualização de mutações para ler a lista atual antes de modificá-la.

cache.writeQuery({ query: GET_USERS, data: { users: updatedUsers } }) grava diretamente no cache, disparando novas renderizações em todos os componentes que leem GET_USERS. Nenhuma solicitação de rede é feita.

Combine readQuery e writeQuery para implementar atualizações imutáveis do cache: leia, produza um novo vetor e grave-o novamente.

cache.modify({ id: cache.identify(user), fields: { name: () => 'New Name' } }) modifica diretamente os campos de uma entidade específica armazenada em cache. Não é necessário ler uma consulta primeiro quando você conhece o ID de cache da entidade.

O objeto fields mapeia nomes de campos para funções modificadoras que recebem o valor atual e retornam o novo valor.

Passe uma função de atualização para useMutation: useMutation(ADD_POST, { update(cache, { data: { addPost } }) { cache.modify({ id: cache.identify(user), fields: { posts: existingPosts => [...existingPosts, addPost] } }); } }).

Isso acrescenta a nova publicação ao vetor de publicações do usuário armazenado no cache, atualizando todos os componentes que exibem a lista de publicações do usuário.

cache.evict({ id: 'User:1' }) remove a entrada User:1 do cache. Qualquer consulta ativa que incluía User:1 será renderizada novamente com essa entidade ausente do resultado.

Depois de remover entradas, chame cache.gc() para remover objetos que agora estão inacessíveis a partir das consultas raiz. Isso evita vazamentos de memória em aplicações de longa duração.

cache.gc() percorre o grafo do cache começando por todas as consultas ativas e remove as entidades que não podem mais ser alcançadas. É seguro chamá-la periodicamente ou após mutações em lote que excluam muitas entidades.

Entidades referenciadas por hooks useQuery ativos nunca são coletadas; somente entidades órfãs que não fazem mais parte de nenhum resultado de consulta são removidas.

Se você consultar uma única entidade (GET_USER por id) que já esteja armazenada em cache como parte de uma consulta de lista, o Apollo poderá lê-la do cache sem uma ida e volta à rede usando políticas de campos: keyArgs e funções read na política de tipo.

A função read retorna uma referência de cache: return toReference({ __typename: 'User', id: args.id }), informando ao Apollo que deve ler a partir da entrada de cache User:id existente.

Se suas entidades usarem um campo diferente de id como chave exclusiva (por exemplo, slug ou uuid), configure-o na política de tipo: new InMemoryCache({ typePolicies: { Post: { keyFields: ['slug'] } } }).

O Apollo passará a usar Post:my-post-slug como chave do cache, em vez de exigir um campo id, preservando a normalização para esquemas não padronizados.

refetchQueries: [{ query: GET_USERS }] nas opções de useMutation dispara uma nova busca pela rede após a conclusão da mutação. É mais simples, mas sempre faz uma solicitação de rede.

A função update modifica o cache localmente e evita a ida e volta à rede. Use refetchQueries quando a lógica de atualização do cache for complexa demais para ser escrita ou quando campos calculados pelo servidor tornarem as atualizações locais pouco confiáveis.

Qual é o formato padrão da chave de cache usado pelo InMemoryCache para armazenar entidades?

O InMemoryCache normaliza entidades por __typename+id, permitindo atualizações automáticas entre consultas. Leia e grave o cache com cache.readQuery, cache.writeQuery e cache.modify. Remova entidades com cache.evict seguido de cache.gc. Configure campos de chave personalizados por meio de typePolicies para chaves primárias diferentes de id.

Use funções de atualização de mutações para obter eficiência no cache local; use refetchQueries quando campos calculados pelo servidor tornarem as atualizações locais pouco confiáveis.