fix(react-data-query): Retain queries in cache until GC (#9502)

## Explanation

Following this PR, instead of automatically removing queries from the UI
query client when a `BaseDataService` instance evicts it from the cache,
we retain the query in cache until the `QueryClient` itself cleans it up
(via `cacheTime`).

This prevents issues with observers in the UI having their cache wiped
just because a refetch hasn't happened in a while. Since the UI query
client considers the data stale, it may also choose to refetch and
repopulate the query in the `BaseDataService` instance before eviction
anyways.

## References

https://consensyssoftware.atlassian.net/browse/WPC-1168

## Checklist

- [x] I've updated the test suite for new or updated code as appropriate
- [x] I've updated documentation (JSDoc, Markdown, etc.) for new or
updated code as appropriate
- [x] I've communicated my changes to consumers by [updating changelogs
for packages I've
changed](https://github.com/MetaMask/core/tree/main/docs/processes/updating-changelogs.md)
- [ ] I've introduced [breaking
changes](https://github.com/MetaMask/core/tree/main/docs/processes/breaking-changes.md)
in this PR and have prepared draft pull requests for clients and
consumer packages to resolve them


<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Changes cache lifecycle for all data-service-backed queries and could
leave stale UI data visible longer if service eviction was relied on for
freshness, though invalidation/hydration paths are unchanged.
> 
> **Overview**
> **UI query cache no longer mirrors `BaseDataService` evictions.** When
the data service publishes a granular `removed` cache update,
`createUIQueryClient` now ignores that event instead of calling
`cache.remove`, so subscribed UI observers keep their data until
TanStack Query’s own `cacheTime` garbage collection runs.
> 
> Tests replace the old “sync removal on remove event” case with
fake-timer coverage: cache stays populated while observers are active
even after the service’s long TTL, and entries are cleared only after
observers are destroyed and the client `cacheTime` elapses. Changelog
records the fix under Unreleased.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
a2a6848. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: FrederikBolding

packages/react-data-query/CHANGELOG.md

@@ -12,6 +12,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Bump `@metamask/utils` from `^11.9.0` to `^11.11.0` ([#9074](https://github.com/MetaMask/core/pull/9074))
 - Make `react-dom` and `react-native` peer dependencies optional ([#9295](https://github.com/MetaMask/core/pull/9295))
 
+### Fixed
+
+- Retain queries in cache until GC ([#9502](https://github.com/MetaMask/core/pull/9502))
+
 ## [0.2.1]
 
 ### Changed

packages/react-data-query/src/createUIQueryClient.test.ts

@@ -1,9 +1,10 @@
 import { Messenger } from '@metamask/messenger';
+import { Duration, inMilliseconds } from '@metamask/utils';
 import {
-  hashQueryKey,
   InfiniteData,
   InfiniteQueryObserver,
   QueryClient,
+  QueryClientConfig,
   QueryObserver,
 } from '@tanstack/query-core';
 
@@ -23,7 +24,7 @@ import { createUIQueryClient } from './createUIQueryClient';
 
 const DATA_SERVICES = ['ExampleDataService'];
 
-function createClients(): {
+function createClients(config?: QueryClientConfig): {
   service: ExampleDataService;
   clientA: QueryClient;
   clientB: QueryClient;
@@ -40,8 +41,8 @@ function createClients(): {
   >({ namespace: 'ExampleDataService' });
   const service = new ExampleDataService(serviceMessenger);
 
-  const clientA = createUIQueryClient(DATA_SERVICES, serviceMessenger);
-  const clientB = createUIQueryClient(DATA_SERVICES, serviceMessenger);
+  const clientA = createUIQueryClient(DATA_SERVICES, serviceMessenger, config);
+  const clientB = createUIQueryClient(DATA_SERVICES, serviceMessenger, config);
 
   return { service, clientA, clientB, messenger: serviceMessenger };
 }
@@ -67,8 +68,12 @@ describe('createUIQueryClient', () => {
     mockTransactionsPage2();
   });
 
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
   it('proxies requests to the underlying service', async () => {
-    const { clientA: client } = createClients();
+    const { clientA: client, service } = createClients();
 
     const result = await client.fetchQuery({
       queryKey: getAssetsQueryKey,
@@ -94,10 +99,12 @@ describe('createUIQueryClient', () => {
         symbol: 'ETH',
       },
     ]);
+
+    service.destroy();
   });
 
   it('fetches using observers', async () => {
-    const { clientA, clientB } = createClients();
+    const { clientA, clientB, service } = createClients();
 
     const observerA = new QueryObserver(clientA, {
       queryKey: getAssetsQueryKey,
@@ -132,10 +139,11 @@ describe('createUIQueryClient', () => {
 
     observerA.destroy();
     observerB.destroy();
+    service.destroy();
   });
 
   it('fetches using observers in the same client', async () => {
-    const { clientA } = createClients();
+    const { clientA, service } = createClients();
 
     const observerA = new QueryObserver(clientA, {
       queryKey: getAssetsQueryKey,
@@ -170,10 +178,11 @@ describe('createUIQueryClient', () => {
 
     observerA.destroy();
     observerB.destroy();
+    service.destroy();
   });
 
   it('synchronizes caches after invalidation', async () => {
-    const { clientA, clientB } = createClients();
+    const { clientA, clientB, service } = createClients();
 
     const observerA = new QueryObserver(clientA, {
       queryKey: getAssetsQueryKey,
@@ -216,10 +225,13 @@ describe('createUIQueryClient', () => {
 
     observerA.destroy();
     observerB.destroy();
+    service.destroy();
   });
 
-  it('synchronizes cache removal after remove event', async () => {
-    const { messenger, clientA, clientB } = createClients();
+  it('does not remove from the cache if observers still are subscribed', async () => {
+    jest.useFakeTimers();
+
+    const { clientA, clientB, service } = createClients();
 
     const observerA = new QueryObserver(clientA, {
       queryKey: getAssetsQueryKey,
@@ -231,40 +243,92 @@ describe('createUIQueryClient', () => {
 
     const promiseA = new Promise((resolve) => {
       observerA.subscribe((event) => {
-        if (event.status === 'success') {
+        if (event.status === 'success' && !event.isFetching) {
           resolve(event.data);
         }
       });
     });
 
     const promiseB = new Promise((resolve) => {
       observerB.subscribe((event) => {
-        if (event.status === 'success') {
+        if (event.status === 'success' && !event.isFetching) {
           resolve(event.data);
         }
       });
     });
 
+    jest.advanceTimersByTime(0);
+
     await Promise.all([promiseA, promiseB]);
 
-    const hash = hashQueryKey(getAssetsQueryKey);
+    // Advance the full cacheTime of ExampleDataService
+    jest.advanceTimersByTime(inMilliseconds(1, Duration.Day));
+
+    const queryData = clientA.getQueryData(getAssetsQueryKey);
+
+    expect(queryData).toBeDefined();
+    expect(queryData).toStrictEqual(clientB.getQueryData(getAssetsQueryKey));
 
-    messenger.publish(`ExampleDataService:cacheUpdated:${hash}`, {
-      type: 'removed',
-      state: null,
+    observerA.destroy();
+    observerB.destroy();
+    service.destroy();
+  });
+
+  it('cleans up removed cache entries once all observers are removed', async () => {
+    jest.useFakeTimers();
+
+    const defaultOptions = {
+      queries: { cacheTime: inMilliseconds(5, Duration.Minute) },
+    };
+
+    const { clientA, clientB, service } = createClients({ defaultOptions });
+
+    const observerA = new QueryObserver(clientA, {
+      queryKey: getAssetsQueryKey,
     });
 
+    const observerB = new QueryObserver(clientB, {
+      queryKey: getAssetsQueryKey,
+    });
+
+    const promiseA = new Promise((resolve) => {
+      observerA.subscribe((event) => {
+        if (event.status === 'success' && !event.isFetching) {
+          resolve(event.data);
+        }
+      });
+    });
+
+    const promiseB = new Promise((resolve) => {
+      observerB.subscribe((event) => {
+        if (event.status === 'success' && !event.isFetching) {
+          resolve(event.data);
+        }
+      });
+    });
+
+    jest.advanceTimersByTime(0);
+
+    await Promise.all([promiseA, promiseB]);
+
+    jest.advanceTimersByTime(inMilliseconds(1, Duration.Day));
+
     const queryData = clientA.getQueryData(getAssetsQueryKey);
 
-    expect(queryData).toBeUndefined();
+    expect(queryData).toBeDefined();
     expect(queryData).toStrictEqual(clientB.getQueryData(getAssetsQueryKey));
 
     observerA.destroy();
     observerB.destroy();
+
+    jest.advanceTimersByTime(inMilliseconds(5, Duration.Minute));
+
+    expect(clientA.getQueryData(getAssetsQueryKey)).toBeUndefined();
+    service.destroy();
   });
 
   it('fetches using paginated observers', async () => {
-    const { clientA, clientB } = createClients();
+    const { clientA, clientB, service } = createClients();
 
     const getPreviousPageParam = ({
       pageInfo,
@@ -323,6 +387,7 @@ describe('createUIQueryClient', () => {
 
     observerA.destroy();
     observerB.destroy();
+    service.destroy();
   });
 
   it('errors if observer attempts to use default query function without a data service', async () => {

packages/react-data-query/src/createUIQueryClient.ts

@@ -112,14 +112,10 @@ export function createUIQueryClient(
         payload: DataServiceGranularCacheUpdatedPayload,
       ): void => {
         if (payload.type === 'removed') {
-          const currentQuery = cache.get(hash);
-
-          if (currentQuery) {
-            cache.remove(currentQuery);
-          }
-        } else {
-          hydrate(client, payload.state);
+          return;
         }
+
+        hydrate(client, payload.state);
       };
 
       subscriptions.set(hash, cacheListener);