refactor(core): Use a Map internally for the QueryCache

* refactor(core): Use a Map internally instead of an Object + an Array

* feat(core): Allow users to provide a custom cache creator function

* test(core): Add tests for custom query cache

* refactor(core): Use public constructor parameter

* refactor(core): experimental_createStore

- rename from createCache
- expose store interface
- pass in the cache into the createStore function (this is a bit weird because cache.queries doesn't exist yet, but it does once the store is created and returned :/
- add another test that checks if the "size limit" use-case works
- mark as experimental because the interface might not be final

* oops

* refactor(core): expose cache from query

so that we can access query.queryCache to find and remove other queries

* docs: docs for custom store

* types: export the QueryStore type

* feat(custom-cache): revert exposing custom cache

most things can be done by doing queryCache.subscribe, and we can still add this later if necessary

* feat(custom-cache): cleanup forgotton export

* stabilize a test

Author: TkDodo

docs/config.json

@@ -177,16 +177,16 @@
               "to": "react/guides/does-this-replace-client-state"
             },
             {
-              "label": "Migrating to React Query 3",
+              "label": "Migrating to v3",
               "to": "react/guides/migrating-to-react-query-3"
             },
             {
-              "label": "Migrating to React Query 4",
+              "label": "Migrating to v4",
               "to": "react/guides/migrating-to-react-query-4"
             },
             {
-              "label": "Migrating to React Query 5",
-              "to": "react/guides/migrating-to-react-query-5"
+              "label": "Migrating to v5",
+              "to": "react/guides/migrating-v5"
             }
           ]
         },

docs/react/guides/migrating-to-react-query-5.md renamed to docs/react/guides/migrating-to-v5.md

@@ -1,5 +1,5 @@
 ---
-id: migrating-to-react-query-5
+id: migrating-to-v5
 title: Migrating to TanStack Query v5
 ---
 

packages/query-core/src/query.ts

@@ -159,7 +159,6 @@ export class Query<
   private observers: QueryObserver<any, any, any, any, any>[]
   private defaultOptions?: QueryOptions<TQueryFnData, TError, TData, TQueryKey>
   private abortSignalConsumed: boolean
-
   constructor(config: QueryConfig<TQueryFnData, TError, TData, TQueryKey>) {
     super()
 
@@ -174,11 +173,9 @@ export class Query<
     this.initialState = config.state || getDefaultState(this.options)
     this.state = this.initialState
   }
-
   get meta(): QueryMeta | undefined {
     return this.options.meta
   }
-
   private setOptions(
     options?: QueryOptions<TQueryFnData, TError, TData, TQueryKey>,
   ): void {

packages/query-core/src/queryCache.ts

@@ -15,10 +15,6 @@ interface QueryCacheConfig {
   onSuccess?: (data: unknown, query: Query<unknown, unknown, unknown>) => void
 }
 
-interface QueryHashMap {
-  [hash: string]: Query<any, any, any, any>
-}
-
 interface NotifyEventQueryAdded {
   type: 'added'
   query: Query<any, any, any, any>
@@ -72,16 +68,10 @@ type QueryCacheListener = (event: QueryCacheNotifyEvent) => void
 // CLASS
 
 export class QueryCache extends Subscribable<QueryCacheListener> {
-  config: QueryCacheConfig
-
-  private queries: Query<any, any, any, any>[]
-  private queriesMap: QueryHashMap
+  private queries = new Map<string, Query>()
 
-  constructor(config?: QueryCacheConfig) {
+  constructor(public config: QueryCacheConfig = {}) {
     super()
-    this.config = config || {}
-    this.queries = []
-    this.queriesMap = {}
   }
 
   build<TQueryFnData, TError, TData, TQueryKey extends QueryKey>(
@@ -111,9 +101,9 @@ export class QueryCache extends Subscribable<QueryCacheListener> {
   }
 
   add(query: Query<any, any, any, any>): void {
-    if (!this.queriesMap[query.queryHash]) {
-      this.queriesMap[query.queryHash] = query
-      this.queries.push(query)
+    if (!this.queries.has(query.queryHash)) {
+      this.queries.set(query.queryHash, query)
+
       this.notify({
         type: 'added',
         query,
@@ -122,15 +112,13 @@ export class QueryCache extends Subscribable<QueryCacheListener> {
   }
 
   remove(query: Query<any, any, any, any>): void {
-    const queryInMap = this.queriesMap[query.queryHash]
+    const queryInMap = this.queries.get(query.queryHash)
 
     if (queryInMap) {
       query.destroy()
 
-      this.queries = this.queries.filter((x) => x !== query)
-
       if (queryInMap === query) {
-        delete this.queriesMap[query.queryHash]
+        this.queries.delete(query.queryHash)
       }
 
       this.notify({ type: 'removed', query })
@@ -139,7 +127,7 @@ export class QueryCache extends Subscribable<QueryCacheListener> {
 
   clear(): void {
     notifyManager.batch(() => {
-      this.queries.forEach((query) => {
+      this.getAll().forEach((query) => {
         this.remove(query)
       })
     })
@@ -149,15 +137,17 @@ export class QueryCache extends Subscribable<QueryCacheListener> {
     TQueryFnData = unknown,
     TError = Error,
     TData = TQueryFnData,
-    TQueyKey extends QueryKey = QueryKey,
+    TQueryKey extends QueryKey = QueryKey,
   >(
     queryHash: string,
-  ): Query<TQueryFnData, TError, TData, TQueyKey> | undefined {
-    return this.queriesMap[queryHash]
+  ): Query<TQueryFnData, TError, TData, TQueryKey> | undefined {
+    return this.queries.get(queryHash) as
+      | Query<TQueryFnData, TError, TData, TQueryKey>
+      | undefined
   }
 
   getAll(): Query[] {
-    return this.queries
+    return [...this.queries.values()]
   }
 
   find<TQueryFnData = unknown, TError = Error, TData = TQueryFnData>(
@@ -167,13 +157,16 @@ export class QueryCache extends Subscribable<QueryCacheListener> {
       filters.exact = true
     }
 
-    return this.queries.find((query) => matchQuery(filters, query))
+    return this.getAll().find((query) => matchQuery(filters, query)) as
+      | Query<TQueryFnData, TError, TData>
+      | undefined
   }
 
   findAll(filters: QueryFilters = {}): Query[] {
+    const queries = this.getAll()
     return Object.keys(filters).length > 0
-      ? this.queries.filter((query) => matchQuery(filters, query))
-      : this.queries
+      ? queries.filter((query) => matchQuery(filters, query))
+      : queries
   }
 
   notify(event: QueryCacheNotifyEvent) {
@@ -186,15 +179,15 @@ export class QueryCache extends Subscribable<QueryCacheListener> {
 
   onFocus(): void {
     notifyManager.batch(() => {
-      this.queries.forEach((query) => {
+      this.getAll().forEach((query) => {
         query.onFocus()
       })
     })
   }
 
   onOnline(): void {
     notifyManager.batch(() => {
-      this.queries.forEach((query) => {
+      this.getAll().forEach((query) => {
         query.onOnline()
       })
     })

packages/query-core/src/tests/queryCache.test.tsx

@@ -1,5 +1,5 @@
 import { sleep, queryKey, createQueryClient } from './utils'
-import type { QueryClient } from '..'
+import { QueryClient } from '..'
 import { QueryCache, QueryObserver } from '..'
 import type { Query } from '.././query'
 import { waitFor } from '@testing-library/react'
@@ -94,6 +94,46 @@ describe('queryCache', () => {
       await sleep(100)
       expect(callback).toHaveBeenCalled()
     })
+
+    test('should be able to limit cache size', async () => {
+      const testCache = new QueryCache()
+
+      const unsubscribe = testCache.subscribe((event) => {
+        if (event.type === 'added') {
+          if (testCache.getAll().length > 2) {
+            testCache
+              .findAll({
+                type: 'inactive',
+                predicate: (q) => q !== event.query,
+              })
+              .forEach((query) => {
+                testCache.remove(query)
+              })
+          }
+        }
+      })
+
+      const testClient = new QueryClient({ queryCache: testCache })
+
+      await testClient.prefetchQuery({
+        queryKey: ['key1'],
+        queryFn: () => 'data1',
+      })
+      expect(testCache.findAll().length).toBe(1)
+      await testClient.prefetchQuery({
+        queryKey: ['key2'],
+        queryFn: () => 'data2',
+      })
+      expect(testCache.findAll().length).toBe(2)
+      await testClient.prefetchQuery({
+        queryKey: ['key3'],
+        queryFn: () => 'data3',
+      })
+      expect(testCache.findAll().length).toBe(1)
+      expect(testCache.findAll()[0]!.state.data).toBe('data3')
+
+      unsubscribe()
+    })
   })
 
   describe('find', () => {
@@ -286,15 +326,15 @@ describe('queryCache', () => {
 
       // Directly add the query from the cache
       // to simulate a race condition
-      const query = queryCache['queriesMap'][hash] as Query
+      const query = queryCache['queries'].get(hash) as Query
       const queryClone = Object.assign({}, query)
 
       // No error should be thrown when trying to add the query
       queryCache.add(queryClone)
-      expect(queryCache['queries'].length).toEqual(1)
+      expect(queryCache.getAll().length).toEqual(1)
 
       // Clean-up to avoid an error when queryClient.clear()
-      delete queryCache['queriesMap'][hash]
+      queryCache['queries'].delete(hash)
     })
 
     describe('QueryCache.remove', () => {
@@ -309,9 +349,9 @@ describe('queryCache', () => {
 
         // Directly remove the query from the cache
         // to simulate a race condition
-        const query = queryCache['queriesMap'][hash] as Query
+        const query = queryCache['queries'].get(hash) as Query
         const queryClone = Object.assign({}, query)
-        delete queryCache['queriesMap'][hash]
+        queryCache['queries'].delete(hash)
 
         // No error should be thrown when trying to remove the query
         expect(() => queryCache.remove(queryClone)).not.toThrow()

packages/react-query/src/__tests__/useQuery.test.tsx

@@ -673,26 +673,29 @@ describe('useQuery', () => {
 
   it('should call onSettled after a query has been fetched with an error', async () => {
     const key = queryKey()
-    const states: UseQueryResult<string>[] = []
     const onSettled = jest.fn()
+    const error = new Error('error')
 
     function Page() {
       const state = useQuery({
         queryKey: key,
-        queryFn: () => Promise.reject<unknown>('error'),
+        queryFn: async () => {
+          await sleep(10)
+          return Promise.reject(error)
+        },
         retry: false,
         onSettled,
       })
-      states.push(state)
-      return null
+      return <div>status: {state.status}</div>
     }
 
-    renderWithClient(queryClient, <Page />)
+    const rendered = renderWithClient(queryClient, <Page />)
 
-    await sleep(10)
-    expect(states.length).toBe(2)
+    await waitFor(() => {
+      rendered.getByText('status: error')
+    })
     expect(onSettled).toHaveBeenCalledTimes(1)
-    expect(onSettled).toHaveBeenCalledWith(undefined, 'error')
+    expect(onSettled).toHaveBeenCalledWith(undefined, error)
   })
 
   it('should not cancel an ongoing fetch when refetch is called with cancelRefetch=false if we have data already', async () => {