Add support for non-serializable query keys or memoization.

[quisido]

I like query keys conceptually because they act a lot like dependency arrays for built-in hooks like useMemo. As long as the dependency array doesn't change, you get the same results, except on a global scale instead of local state.

Unfortunately, query keys fail this memoization concept when it comes to non-serializable keys.

I really, really want to "cache-bust" based on a function, and I cannot for the life of me figure out how to do it well with these serializable keys, so here is a simplified example of my use case:

function App() {
  // Define a stateful/changing API endpoint.
  const [endpoint, setEndpoint] = useState('https://some-api/');

  // Execute the API based on the variable endpoint.
  const callApi = useCallback(() => {
    return fetch(endpoint);
  }, [endpoint]);

  // Pass the API function via context.
  return (
    <>
      <Toggle onChange={setEndpoint} /> // <-- set a different endpoint for the entire application
      <Api.Provider value={callApi}>
        <Child /> // <-- entire application uses the API from context
      </Api.Provider>
    </>
  );
}

Now any of the children can execute this API from the context:

function SomeChild() {
  const callApi = useContext(Api);
  const { data, error, isFetching } = useQuery(
    ['my-api'],
    async () => {
      return await callApi(); // <-- call the API, which can change
    },
    options,
  );
}

Current behavior: When Toggle changes the endpoint, thus changing the callApi function, the fetched data from the last API call remains cached and SomeChild does not rerender unless remove()/refetch() are called manually.

Desired behavior: When Toggle changes the endpoint, thus changing the callApi function, I want SomeChild's use of useQuery to drop its cache and refetch the data.

Expected implementation: Based on existing React patterns, my intuition tells me I should be able to list [callApi] as a dependency array to useQuery instead of the string 'my-api'. I would also value a onDependencyArrayChange that lets me clear the previous cache, which I no longer need.

[TkDodo]

Maybe you've just posted a simplified example, but if that is indeed your code, I would argue that the endpoint is the real dependency, not the callApi function. I would:

• share the endpoint state via context
• add the endpoint to the query key, thus formulating the dependency
• call fetch(endpoint) in the queryFn. Of course, if the fetch is more complex but the same for every invocation of useQuery, the default query function comes in handy. Since you have the endpoint inside the queryKey, the default query fn will also have access to it.

I would also value a onDependencyArrayChange that lets me clear the previous cache, which I no longer need.

you can set the cacheTime to tell react-query for how long you would like to keep the values in the cache even if they are unused. set it to 0, and if you follow the above described pattern and add the endpoint to the queryKey, they will be removed once the endpoint changes (if there are not consumers using it)

[quisido]

This is a simplified example, where endpoint (the dependency of my function) isn't simply a string, but a non-serializable object and complex collection of dependencies, for which I do not want to have to pass all of them and construct them in every use of useQuery.

I think abstraction has value here, and having endpoint (or the collection of dependencies that combined to create a complex, non-serializable object) hidden from the consuming components is an ideal pattern. The calling components do not need to know the complexities of how the callApi is created, and a change to callApi should not require a change to every calling component.

you can set the cacheTime to tell react-query for how long you would like to keep the values in the cache even if they are unused.

Is this different than staleTime? I am using a staleTime of infinity because I don't want to refetch the data as components mount and unmount. I only want the cache to be cleared when the dependency array changes, but not on component unmount. Obscure use case, but it matches the pattern I described in my code example above.

I am having to do "whenever callApi changes, queryClient.clear()," but that seems really code smell, because the creator of callApi should not need to know that I am using react-query to cache it. I also don't necessarily want all uses of react-query to have their caches cleared -- just the ones that use callApi. I strongly feel like react-query here is what's not offering the desirable API in line with what other libraries or React itself offers as standard practices. Don't get me wrong, I love react-query and that's why I'm using it, but I feel like it could be improved by this change to make it more intuitive (per React built in patterns) and support this use case, which I feel is a valid use case for react-query.

[TkDodo]

Is this different than staleTime? I am using a staleTime of infinity because I don't want to refetch the data as components mount and unmount.

Yes, it is. A summary from my blog post:

StaleTime: The duration until a query transitions from fresh to stale. As long as the query is fresh, data will always be read from the cache only - no network request will happen! If the query is stale (which per default is: instantly), you will still get data from the cache, but a background refetch can happen under certain conditions.

CacheTime: The duration until inactive queries will be removed from the cache. This defaults to 5 minutes. Queries transition to the inactive state as soon as there are no observers registered, so when all components which use that query have unmounted.

So I think you have set staleTime correctly, but you also want to set a lower cacheTime so that unused queries are cleaned up.

I only want the cache to be cleared when the dependency array changes

A change of the queryKey will result in a new cache entry and will leave the old one in the cache. If you set cacheTime:0 and have no other observers, the old entry will be removed when the key changes.

endpoint (the dependency of my function) isn't simply a string, but a non-serializable object and complex collection of dependencies, for which I do not want to have to pass all of them and construct them in every use of useQuery.

so the query cache is just an object, and the queryKey forms the key of that key-value store. Thus it must be serializable of some sort, it must be a valid javascript object key. You can however provide your own queryKeyHashFn as an option to useQuery where you can create a stable cache key for yourselves. It will be tricky if the only thing you have is a function though

[quisido]

A change of the queryKey will result in a new cache entry and will leave the old one in the cache.

The reason I request a "dependency array" instead of a "query key" is because my only way to uniquely identify the query is non-serializable (it's a function). This function may be called in 20 different components, and I do not think it's reasonable to edit all 20 different function-invoking components to change the query key every time the dependencies of the function itself changes.

If you set cacheTime:0 and have no other observers, the old entry will be removed when the key changes.

Thanks for the suggestion. I'll use it. I do not want the cache to bust when no observers are present (as I want it to still be present when those components remount), but I believe this is not a reasonable ask. I think a non-zero cache time will serve the use case of busting old caches well enough.

But I maintain the need to use a non-serializable item as a query key.

so the query cache is just an object, and the queryKey forms the key of that key-value store. Thus it must be serializable of some sort, it must be a valid javascript object key. You can however provide your own queryKeyHashFn as an option to useQuery where you can create a stable cache key for yourselves. It will be tricky if the only thing you have is a function though

React hooks work similarly with dependency arrays, but they are not limited to serializable keys. Perhaps react-query should adopt a similar approach. Perhaps using a Map or WeakMap instead of a vanilla object? Or even using both -- serializable when it is, and a fallback to a map when it isn't.

I'm not familiar with the shape of the store, but I'll free-hand my contrived assumption:

class Store {
  private _state: Record<string, unknown> = {};

  public setState(queryKey: (number | string)[], value: unknown) {
    this._state[queryKey.join('.')] = value;
  }

  public getState(queryKey: (number | string)[]): unknown {
    return this._state[queryKey.join('.')];
  }
}

This is a proposed refactor:

/*
Determine if two arrays contain equal items. This addresses array reference changes across re-renders.
  const one = [func1, func2];
  const two = [func1, func2];
  one == two; // false
  isArrayEqual(one, two); // true
*/
const isArrayEqual = <T>(one: T[], two: unknown[]): two is T[] => {
  // If they are different length, they can't be equal.
  if (one.length !== two.length) {
    return false;
  }

  // If any item is different, these aren't equal dependency arrays.
  for (let i = 0; i < one.length; i++) {
    if (one[i] !== two[i]) {
      return false;
    }
  }

  // All items matched.
  return true;
};

/*
Given a collection of dependency arrays in cache, find the dependency array reference
  that matches the provided one. This addresses dependency array references
  changing between renders.
*/
const findDependencyArray = (
  dependencyArrrays: unknown[][],
  dependencyArray: unknown[],
): unknown[] | undefined =>
  dependencyArrays.find((arr: unknown[]): boolean => isArrayEqual(arr, dependencyArray));

class Store {
  private _referenceState: Map<unknown[], unknown> = new Map();
  private _state: Record<string, unknown> = {};

  public setState(queryKey: (number | string)[], value: unknown) {
    // Current serializable behavior
    if (isSerializable(queryKey)) {
      this._state[queryKey.join('.')] = value;
      return;
    }

    // Non-serializable behavior

    // Sort the dependency array so that [func1, func2] == [func2, func1]
    const dependencyArray: unknown[] = [...queryKeys].sort();

    // Find this dependency array in the cache.
    const cachedDependencyArray: unknown[] | undefined = findDependencyArray(
      this._referenceState.keys(),
      dependencyArray,
    );

    // Set this dependency array to the new value.
    this._referenceState.set(cachedDependencyArray || dependencyArray, value);
  }

  public getState(queryKey: (number | string)[]): unknown {
    // Serializable behavior
    if (isSerializable(queryKey)) {
      return this._state[queryKey.join('.')];
    }

    // Non-serializable behavior.

    // Sort the dependency array so that [func1, func2] == [func2, func1]
    const dependencyArray: unknown[] = [...queryKeys].sort();

    // Find this dependency array in the cache.
    const cachedDependencyArray: unknown[] | undefined = findDependencyArray(
      this._referenceState.keys(),
      dependencyArray,
    );

    // Get the value of this dependency array.
    return this._referenceState.get(cachedDependencyArray || dependencyArray);
  }
}

Implementation details can change however they need to. I think the overall idea is that it is possible to use non-serializable keys, much the same way React itself uses non-serializable keys to cache. This reflects my use case that the only thing exposed to useQuery is the function it is calling and my need to cache-bust whenever that function changes.

[HHogg]

I have a similar use case, where the API abstraction has some inner workings that can be changed in a central point (for example adding some headers). Before using React Query this would be a dependency in a useEffect, and would trigger refetching some data. All of the places using this API abstraction did not need to know about the inner workings of the API but just that it needed to refetch the data. A simplified example, before React Query...

// APIContext.
const { someValue } = useContext(AppContext);

const get = useCallback((url: string) => fetch(url, { 
  headers: { 'Some-Header': someValue },
}), [someValue]);


// Some Consumer
const { get } = useContext(APIContext);

useEffect(() => {
  get('/something');
}, [get]);

With React Query, we assumed this would work...

const { get } = useContext(APIContext);

useQuery(['someKey', { get }], () => get('/something'));

But it does not. What do you think about having a dependency array that is not part of the query cache, that follows a similar pattern to all other hooks like...

useQuery('someKey', () => get('/something'), {}, [get]);

// or 

useQuery('someKey', () => get('/something'), { dependencies: [get] });

[tannerlinsley]

While there may be very far corner cases for supporting non-serializable items in the query key, it's definitely not a majority use case and I believe many workarounds exist, some of them have even been discussed in this thread already. With that said, I feel it's not in our immediate roadmap to support this use case. This doesn't mean we won't in the future though.

[HHogg]

Thanks for the reply @tannerlinsley. I really hope that we can revisit this in the future. Even if it is only causing an issue in edge cases, I feel not having this behaviour breaks the common/standard pattern of external dependencies used in hooks, being able to trigger the hook.