feat(experimental_createQueryPersister): Add removeQueries (#10186)

rklomp · autofix-ci[bot] · coderabbitai[bot] · web-flow · commit 978fc52728a8 · 2026-02-26T12:44:41.000+01:00
* Add removeQueries

* Docs

* ci: apply automated fixes

* Fix test

* Add changeset

* Udpate docs

* Await removeItem

* Improve test names

* Update .changeset/fifty-zebras-stay.md

Co-authored-by: coderabbitai[bot] &lt;136622811+coderabbitai[bot]@users.noreply.github.com&gt;

* Add coderabbitai suggestion

* More data integrity checks

* removeItem if deserialize fails

* removeItem if deserialize fails in retrieveQuery as well

* removeItem if deserialize fails in restoreQueries

* Revert changes outside removeQueries scope

---------

Co-authored-by: autofix-ci[bot] &lt;114827586+autofix-ci[bot]@users.noreply.github.com&gt;
Co-authored-by: coderabbitai[bot] &lt;136622811+coderabbitai[bot]@users.noreply.github.com&gt;
diff --git a/.changeset/fifty-zebras-stay.md b/.changeset/fifty-zebras-stay.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/query-persist-client-core': minor
+---
+
+Add removeQueries to experimental_createQueryPersister
diff --git a/docs/framework/react/plugins/createPersister.md b/docs/framework/react/plugins/createPersister.md
@@ -126,6 +126,21 @@ The filter object supports the following properties:
 For this function to work, your storage must expose `entries` method that would return a `key-value tuple array`.  
 For example `Object.entries(localStorage)` for `localStorage` or `entries` from `idb-keyval`.
 
+### `removeQueries(filters): Promise<void>`
+
+When using `queryClient.removeQueries`, the data remains in the persister and needs to be removed separately.
+This function can be used to remove queries that are currently stored by persister.
+
+The filter object supports the following properties:
+
+- `queryKey?: QueryKey`
+  - Set this property to define a query key to match on.
+- `exact?: boolean`
+  - If you don't want to search queries inclusively by query key, you can pass the `exact: true` option to return only the query with the exact query key you have passed.
+
+For this function to work, your storage must expose `entries` method that would return a `key-value tuple array`.  
+For example `Object.entries(localStorage)` for `localStorage` or `entries` from `idb-keyval`.
+
 ## API
 
 ### `experimental_createQueryPersister`
diff --git a/packages/query-persist-client-core/src/__tests__/createPersister.test.ts b/packages/query-persist-client-core/src/__tests__/createPersister.test.ts
@@ -675,4 +675,93 @@ describe('createPersister', () => {
       expect(client.getQueryCache().getAll()).toHaveLength(1)
     })
   })
+
+  describe('removeQueries', () => {
+    test('should remove restore queries from storage without filters', async () => {
+      const storage = getFreshStorage()
+      const { persister, client, queryKey } = setupPersister(['foo'], {
+        storage,
+      })
+      client.setQueryData(queryKey, 'foo')
+
+      await persister.persistQueryByKey(queryKey, client)
+
+      expect(await storage.entries()).toHaveLength(1)
+      await persister.removeQueries()
+      expect(await storage.entries()).toHaveLength(0)
+    })
+
+    test('should remove queries from storage', async () => {
+      const storage = getFreshStorage()
+      const { persister, client, queryKey } = setupPersister(['foo', 'bar'], {
+        storage,
+      })
+      client.setQueryData(queryKey, 'foo')
+
+      await persister.persistQueryByKey(queryKey, client)
+
+      expect(await storage.entries()).toHaveLength(1)
+      await persister.removeQueries({ queryKey })
+      expect(await storage.entries()).toHaveLength(0)
+    })
+
+    test('should not remove queries from storage if there is no match', async () => {
+      const storage = getFreshStorage()
+      const { persister, client, queryKey } = setupPersister(['foo', 'bar'], {
+        storage,
+      })
+      client.setQueryData(queryKey, 'foo')
+
+      await persister.persistQueryByKey(queryKey, client)
+
+      expect(await storage.entries()).toHaveLength(1)
+      await persister.removeQueries({ queryKey: ['bar'] })
+      expect(await storage.entries()).toHaveLength(1)
+    })
+
+    test('should properly remove queries from storage with partial match', async () => {
+      const storage = getFreshStorage()
+      const { persister, client, queryKey } = setupPersister(['foo', 'bar'], {
+        storage,
+      })
+      client.setQueryData(queryKey, 'foo')
+
+      await persister.persistQueryByKey(queryKey, client)
+
+      expect(await storage.entries()).toHaveLength(1)
+      await persister.removeQueries({ queryKey: ['foo'] })
+      expect(await storage.entries()).toHaveLength(0)
+    })
+
+    test('should not remove queries from storage with exact match if there is no match', async () => {
+      const storage = getFreshStorage()
+      const { persister, client, queryKey } = setupPersister(['foo', 'bar'], {
+        storage,
+      })
+      client.setQueryData(queryKey, 'foo')
+
+      await persister.persistQueryByKey(queryKey, client)
+
+      expect(await storage.entries()).toHaveLength(1)
+      await persister.removeQueries({ queryKey: ['foo'], exact: true })
+      expect(await storage.entries()).toHaveLength(1)
+    })
+
+    test('should remove queries from storage with exact match', async () => {
+      const storage = getFreshStorage()
+      const { persister, client, queryKey } = setupPersister(['foo', 'bar'], {
+        storage,
+      })
+      client.setQueryData(queryKey, 'foo')
+
+      await persister.persistQueryByKey(queryKey, client)
+
+      expect(await storage.entries()).toHaveLength(1)
+      await persister.removeQueries({
+        queryKey: queryKey,
+        exact: true,
+      })
+      expect(await storage.entries()).toHaveLength(0)
+    })
+  })
 })
diff --git a/packages/query-persist-client-core/src/createPersister.ts b/packages/query-persist-client-core/src/createPersister.ts
@@ -301,12 +301,54 @@ export function experimental_createQueryPersister<TStorageValue = string>({
     }
   }
 
+  async function removeQueries(
+    filters: Pick<QueryFilters, 'queryKey' | 'exact'> = {},
+  ): Promise<void> {
+    const { exact, queryKey } = filters
+
+    if (storage?.entries) {
+      const entries = await storage.entries()
+      const storageKeyPrefix = `${prefix}-`
+      for (const [key, value] of entries) {
+        if (key.startsWith(storageKeyPrefix)) {
+          if (!queryKey) {
+            await storage.removeItem(key)
+            continue
+          }
+
+          let persistedQuery: PersistedQuery
+          try {
+            persistedQuery = await deserialize(value)
+          } catch {
+            await storage.removeItem(key)
+            continue
+          }
+
+          if (exact) {
+            if (persistedQuery.queryHash !== hashKey(queryKey)) {
+              continue
+            }
+          } else if (!partialMatchKey(persistedQuery.queryKey, queryKey)) {
+            continue
+          }
+
+          await storage.removeItem(key)
+        }
+      }
+    } else if (process.env.NODE_ENV === 'development') {
+      throw new Error(
+        'Provided storage does not implement `entries` method. Removal of stored entries is not possible without ability to iterate over storage items.',
+      )
+    }
+  }
+
   return {
     persisterFn,
     persistQuery,
     persistQueryByKey,
     retrieveQuery,
     persisterGc,
     restoreQueries,
+    removeQueries,
   }
 }

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@tanstack/query-persist-client-core': minor
 +---
++
 +Add removeQueries to experimental_createQueryPersister