Improve the cache api

[focux]

I was reading through the docs and didn't find a way to hook into the cache setter and getter, I think that would be a good addition to this library. I usually use Apollo in my projects and one of the things that I really like about it is their normalized cache, it's very useful in large scale apps.

This is an example of what a normalized cache looks like:

1. Suppose we fetch a list of todos and we get this response:

{
  todos: [
      {
          id: 1,
          comment: 'something',
          user: {
              id: 1,
              name: 'John'
          }
      },
      {
          id: 2,
          comment: 'another one',
          user: {
              id: 2,
              name: 'Maria'
          }
      },
      {
          id: 2,
          comment: 'another comment',
          user: {
              id: 1,
              name: 'John'
          }
      }
  ]
}

2. This is how the response would look after normalizing it:

{
    todos: [
        { id: 1, comment: 'something', userId: 1},
        { id: 2, comment: 'another one', userId: 2 },
        { id: 2, comment: 'another comment', userId: 1 },
    ],
    users: [
        { id: 1, name: 'John'},
        { id: 2, name: 'Maria' }
    ]
}

This is highly useful when you have entities/queries sharing the same nested entities. if you, for example, have recently fetched a query that has a user with an updated name, it will update all the queries that are referencing that user.

I'm not sure if that's a strategy that we should adopt in the library but it'd be good if we have a way to hook into the cache maybe through functions like beforeRead and beforeSet.

[osiux]

What I'm doing is normalizing the data in the fetch function:

import { normalize, schema } from 'normalizr';
import { path } from 'ramda';

import api from './api';

const userSchema = new schema.Entity('users');

export const fetchUsers = async () => {
    const users = await api()
        .get('users')
        .json();

    const normalizedData = normalize(users, [userSchema]);
    const data = path(['entities', 'users'], normalizedData) || {};

    return data;
};

This way when I use the function with react-query, cached data is the normalized data.

const { status, data } = useQuery('users', fetchUsers);

And when an update is made, is easy to update the data this way:

import produce from 'immer';

const [userUpdate] = useMutation(updateUser, {
        onSuccess: data => {
            queryCache.setQueryData(
                'users',
                oldData => {
                    return produce(oldData, newData => {
                        newData[data.id] = data;
                    });
                },
            );
        },
    });

[focux]

That looks good for simple cases, but what if you have a nested entity in your user schema, like e.g friends, how would you store the normalized friends object in the cache and how would you resolve it later?

With your approach, I don't think you can do that because you'd need a way to store the friends under another key inside the cache, please tell me if I'm wrong. Thank you for your answer.

[tannerlinsley]

The bottom line here is that once you start normalizing, you start making decisions that incur tradeoffs of performance or built-in staleness. You're more than welcome to implement whatever manual operations with the query cache that you want using queryCache.setQueryData or similar utilities, but for now, no built-in mechanisms or affordances for normalized caching will be built in or native to React Query.

[jackblackCH]

I came here with the same idea. So @tannerlinsley is the solution above to recommended way to work with nested data together with react-query?

E.g I receive a big object with many nested entities, I create a schema that connects it with all keys (with normalizr), and put that flat result into react query? within react query I can then easily update the state on my flat "cache". e.g with Immer or vanilla methods.

[SeanRoberts]

Sorry to bump a very old topic, but if normalizing isn't part of the philosophy of the project is there any discussion or documentation about how to handle situations like @focux brought up? Most larger apps that I've worked on have data entities that are really closely interrelated and I'm sure that's the same for a lot of people. How does react-query (or people who have used it on larger codebases) suggest handling a situation like a user that's represented in a bunch of different queries being updated?

[tannerlinsley]

Right now, the best way forward is to manually normalize that user into the areas of the cache that it's used, or simply invalidate the queries in the app that rely on that normalized user information. Normalized data stores can be very cool if done well, or very problematic if not. We are making sure that we approach the problem correctly before we give any official way forward. For most applications, invalidating related queries and simply refetching the data from the server again is just fine.

[SeanRoberts]

Thanks Tanner, that makes total sense to me. Normalizing it myself isn't a big deal as @osiux suggested above, I just didn't want to go down that path only to find that I was totally at odds with the ideas/goals of react-query. You're right that normalizing out of the box would probably just flood your issue tracker with people who are having issues with the normalizing.

[SeanRoberts]

Actually maybe I'm wrong, @focux brought up the point above about nested entities. For example, if you had an endpoint that returned data like this:

posts: [
  {
    id: 1,
    author: { id: 1, name: 'Bart' },
    comments: [
      {
        id: 1,
        author: { id: 2, name: 'Lisa' }
      },
      {
        id: 2,
        author: { id: 1, name: 'Bart' }
      }
    ]
  },
  {
    id: 2,
    author: { id: 2, name: 'Lisa' },
    comments: [
      {
        id: 3,
        author: { id: 3, name: 'Milhouse' }
      },
      {
        id: 4,
        author: { id: 3, name: 'Milhouse' }
      }
    ]
  }
]

I'd like to be able to store it in my cache like this:

{
  postsIndex: [1, 2],
  posts: {
    1: { commentIds: [1, 2], authorId: 1 },
    2: { commentIds: [3, 4], authorId: 2 }
  },
  comments: {
    1: { authorId: 2 }
    2: { authorId: 1 },
    3: { authorId: 3 },
    4: { authorId: 3 }
  },
  users: {
    1: { name: 'Bart' },
    2: { name: 'Lisa' },
    3: { name: 'Milhouse' }
  }
}

So that for example, if I mutated User 1's name to "El Barto" it would automatically be reflected in that user's posts, comments, etc. Maybe if I want this level of control over my cache it makes more sense to reach for redux? Marking queries as invalidated and just refetching them makes sense too, the issue I have is when an app grows to the point where there are dozens of queries and mutations it can be difficult to remember that, for example, when you add a new query that contains users you need to go back to the updateUser mutation and add that new query to the list of those that need to get invalidated.

[jackblackCH]

I have exactly the same issue and idea. What's the best practice with complex and nested data AND react-query?

[longfellowone]

Give urql a try if you need normalized cacheing

[tannerlinsley]

This is where managing your side effects in a central location is helpful. It’s almost like maintaining a schema of related Query keys. When this key changes, these keys should invalidate. Then just have your mutations reference these central side effects.

[rattrayalex]

@tannerlinsley if someone wanted to build a third-party integration with normalizr for automatic caching, like react-query-normalized, would that be possible with today's API? It seems that it should be, based on @osiux 's solution, but it might have to wrap react-query in awkward ways?

I think this is an important topic (even if not addressed within react-query itself) because many teams choose between GraphQL+Apollo or REST+react-query for their server/client architecture. One of the biggest selling points of graphql+apollo is the normalized caching.

To get that benefit with REST today, you have to do a lot of complicated and ugly manual stuff with redux/mobx, which is a no-go – and not having a normalized cache can make for a broken user experience (update your profile picture or name and don't see it reflected anywhere in the app); also a no-go.

When I worked at Stripe, I helped build a solution that made REST at least as nice to use as GraphQL (basically, an internal version of react-query, before it existed). It autogenerated a function for each operation in our internal openapi spec, complete with types for params and responses, and a normalizr schema for the relations within our app for automatic normalized caching.

Having the cache work in a consistent/automated way kept the system relatively predictable, and each use of a query/mutation had to specify whether it should use the cache, which was a simple solution to the general problem of dealing with caching bugs.

Today, orval exists to generate react-query queries/mutations for everything in an openapi spec, but it doesn't have a normalized caching layer. Once it, or a similar tool, has this, it'll be possible to get substantively all benefits of the GraphQL/Apollo stack with REST/react-query, which is simpler.

@tannerlinsley how would you architect such a library? Can it be done today in an ergonomic way?

[leetrout]

@tannerlinsley any thoughts here? We're also interested in @rattrayalex's proposal. Was there work done on this anywhere else already?

[rattrayalex]

Thanks Lee. I am interested in attempting to explore this in 2022 and will report back here / file issues as appropriate if I run into difficulties.

[jackblackCH]

Same here! Would be nice to see an example with complex nested data and react-query

[klis87]

Hi, I think I actually created exactly what you mentioned in this topic - https://github.com/klis87/normy/tree/master/packages/normy-react-query. Thanks to @normy/core agnostic lib, which adds automatic normalisation and data updates (in apollo fashion) there is already integration with react-query. It also works with trpc.

All you need to do is to add several lines of code and you get data updates without changing how you use react-query - (apart from manual data updates or refetches which you could just remove ;))

[ntucker]

Have you considered using a library intended for high performance and data consistency using data normalization like Reactive Data Client?

This normalization lets you perform data mutations with one line and zero extra fetches. No need to create inconsistencies and performance problems with invalidation fetches.

🎮Simplest Todo Demo | 🎮Github Demo

For example:

import { Entity, createResource } from '@data-client/rest';

export class Todo extends Entity {
  id = 0;
  userId = 0;
  title = '';
  completed = false;
  pk() {
    return `${this.id}`;
  }
  static key = 'Todo';
}
export const TodoResource = createResource({
  urlPrefix: 'https://jsonplaceholder.typicode.com',
  path: '/todos/:id',
  searchParams: {} as { userId?: string | number } | undefined,
  schema: Todo,
  optimistic: true,
});

import { useSuspense } from '@data-client/react';
import { TodoResource } from './TodoResource';
import TodoItem from './TodoItem';
import CreateTodo from './CreateTodo';

function TodoList() {
  const userId = 1;
  const todos = useSuspense(TodoResource.getList, { userId });
  return (
    <div>
      {todos.map(todo => (
        <TodoItem key={todo.pk()} todo={todo} />
      ))}
      <CreateTodo userId={userId} />
    </div>
  );
}

import { useController } from '@data-client/react';
import { TodoResource } from './TodoResource';

export default function CreateTodo({ userId }: { userId: number }) {
  const ctrl = useController();
  const handleKeyDown = async e => {
    if (e.key === 'Enter') {
      ctrl.fetch(TodoResource.getList.push, {
        userId,
        title: e.currentTarget.value,
      });
      e.currentTarget.value = '';
    }
  };
  return (
    <div className="listItem nogap">
      <label>
        <input type="checkbox" name="new" checked={false} disabled />
        <input type="text" onKeyDown={handleKeyDown} />
      </label>
      <CancelButton />
    </div>
  );
}

import { useController } from '@data-client/react';
import { TodoResource, type Todo } from './TodoResource';

export default function TodoItem({ todo }: { todo: Todo }) {
  const ctrl = useController();
  const handleChange = e =>
    ctrl.fetch(
      TodoResource.partialUpdate,
      { id: todo.id },
      { completed: e.currentTarget.checked },
    );
  const handleDelete = () =>
    ctrl.fetch(TodoResource.delete, {
      id: todo.id,
    });
  return (
    <div className="listItem nogap">
      <label>
        <input
          type="checkbox"
          checked={todo.completed}
          onChange={handleChange}
        />
        {todo.completed ? <strike>{todo.title}</strike> : todo.title}
      </label>
      <CancelButton onClick={handleDelete} />
    </div>
  );
}

You could also integrate normalization into another library using the underlying optimized normalizr library

[crabmusket]

I'm building/consuming a backend that follows the JSON:API spec, and it was designed with normalisation of object graphs in mind. I'm just commenting this for now in case anyone else is searching for JSON:API-related keywords. I'm keen to see if I can use this library to build a kind of equivalent of Ember data in Vue.