Understanding query deduplication option merging and dynamic options

[nickbabcock]

I'm struggling to come up with the correct mental model for how Tanstack query handles merging options from multiple useQuery instances and for how dynamic option values impact behavior.

For deduplication, originally I was under the impression that only the options from the request that gets deduplicated to wins out (eg: the component that gets mounted first), but this is not the case as seen in staleTime always taking the most pessimistic value.

const myEndpoint = () =>
  new Promise((res) => setTimeout(res, 5000)).then(() => 'hello world');

function Child() {
  useQuery({
    queryKey: ['example'],
    queryFn: myEndpoint,
    staleTime: Infinity,
  });

  return <div>Child</div>;
}

function App() {
  useQuery({
    queryKey: ['example'],
    queryFn: myEndpoint,
    staleTime: 0,
  });

  return <Child />;
}

The effective staleTime is zero. Are there other options like this, where it is not winner takes all?

Dynamic Options

My mental model for thinking for dynamic options is:

TanStack query only responds to option changes if that option would trigger a new request or it modifies the query's cache calculations

Thus one should, where available, pass in functions that are able to read the latest state.

This has been shaped by a couple examples:

1. updating retryDelay is ineffective

Our query function will always log attempts that are 10 seconds apart. No matter how many times our button is pressed. However, refocusing the window causes a refetch and our new retryDelay is picked up. Why is this?

const myFailingEndpoint = () => {
  console.log(new Date());
  return Promise.reject(new Error('oh no'));
}

function App() {
  const [status, setStatus] = useState(false);

  const client = useQueryClient();
  useQuery({
    queryKey: ['example'],
    queryFn: myFailingEndpoint,
    retryDelay: status ? 1000 : 10000,
  });

  return (
    <button
      onClick={() => {
        setStatus(true);
        client.cancelQueries({ queryKey: ['example'] });
        client.invalidateQueries({ queryKey: ['example'] });
      }}
    >
      Click me
    </button>
  );
}

2. updating staleTime is effective

Showing react query can incorporate changes to queryKey and enabled is pretty straightforward, but I learned that the same is true for staleTime

const myEndpoint = () => {
  console.log('executing');
  return new Promise((res) => setTimeout(res, 10000)).then(() => 'hello world');
};

function App() {
  const [status, setStatus] = useState(false);

  useQuery({
    queryKey: ['example'],
    queryFn: myEndpoint,
    staleTime: status ? Infinity : 0,
  });

  return (
    <button
      onClick={() => {
        setStatus(true);
      }}
    >
      Click me
    </button>
  );
}

The devtools identify that our query is will be fresh after we click the button regardless of whether our request was in the fetching state when we pressed the button

Bonus: how many times will our query function console log? Just once.

Ignoring that inconsistent query options can be a bit of a code smell, is there documentation regarding query option behaviors when they are updated or deduplicated? What is the best mental model to have when reviewing when inconsistent query options are present?

[TkDodo]

TanStack query only responds to option changes if that option would trigger a new request or it modifies the query's cache calculations

that's wrong. options are always updated. Why wouldn't they? There is no "options deduplication" - only "request deduplication".

1. updating retryDelay is ineffective

In this example, setStatus(true); will schedule a re-render. you can't have further calls in the same event handler expect to have updated options already, because that will only happen within the next render cycle. That's how react works.

2. updating staleTime is effective

Here, you don't do anything else in the second event handler, so your examples are not comparable.

[TkDodo]

because, again, that is how react works. You cannot expect the call to client.invalidateQueries have the options updated right after you call setStatus(true). This also doesn't work:

    <button
      onClick={() => {
        setStatus(true);
        console.log(status);
      }}

would you expect status to be true after you call setStatus? If so, you need to work on your understanding of the react mental model...

[nickbabcock]

I don't want you to focus on the first button click. If what you say is true (that options are always updated), then on the second button click, our query that we're invalidating should reference the updated options, no? As no react component is observing the query with outdated options. Yet it is always the first set of options that are effective after invalidation.

[TkDodo]

interesting, thanks for explaining that to me. It seems that only observer properties are being updated, but query options are only taken into account when the query is created. I don't think that is correct - feels more like a bug because it means we can't change values like retryDelay or gcTime. I need to look in to this

[TkDodo]

issue: #3706
pr: #7081

[nickbabcock]

Thank you, I appreciate you sticking with the discussion and taking the time to check things out.

[TkDodo]

PR is merged - please checkout the latest version

[nickbabcock]

Yeah I think we're good, it's just a little unintuitive that the initial fetch uses the child's option, but future ones (ie: on window focus) uses the parent's:

const myEndpoint = ({ meta }) => {
  console.log(meta.name);
  return Promise.resolve('hello world');
};

function Child() {
  useQuery({
    queryKey: ['example'],
    queryFn: myEndpoint,
    meta: { name: 'child' },
  });

  return <div>Child</div>;
}

function App() {
  const client = useQueryClient();
  useQuery({
    queryKey: ['example'],
    queryFn: myEndpoint,
    meta: { name: 'parent' },
  });

  return (
    <>
      <Child />
      <button
        onClick={() => {
          client.cancelQueries({ queryKey: ['example'] });
          client.invalidateQueries({ queryKey: ['example'] });
        }}
      >
        Click me
      </button>
    </>
  );
}

I get why this happens, but figured I'd voice that sometimes the mental model can be tricky (and that can be ok, you're out here solving tough problems -- and we're probably far enough from best practices that it's moot 😄 ).

EDIT: the example is particularly intriguing as the query alternates between logging "child" and "parent" depending on if the query is invalidated or refetched

[TkDodo]

meta isn't supposed to be a dynamic value that is different per component. Just like the queryFn, there is only one stored in the cache. Please just don't do this