feat: implement batch rendering (#989)

docs/src/pages/docs/comparison.md

@@ -33,26 +33,29 @@ Feature/Capability Key:
 | Scroll Recovery                              | ✅                                     | ✅                         | ✅                                  |
 | Cache Manipulation                           | ✅                                     | ✅                         | ✅                                  |
 | Outdated Query Dismissal                     | ✅                                     | ✅                         | ✅                                  |
+| Render Optimization<sup>2</sup>              | ✅                                     | 🛑                         | 🛑                                  |
 | Auto Garbage Collection                      | ✅                                     | 🛑                         | 🛑                                  |
 | Mutation Hooks                               | ✅                                     | 🟡                         | ✅                                  |
 | Prefetching APIs                             | ✅                                     | 🔶                         | ✅                                  |
 | Query Cancellation                           | ✅                                     | 🛑                         | 🛑                                  |
-| Partial Query Matching<sup>2</sup>           | ✅                                     | 🛑                         | 🛑                                  |
+| Partial Query Matching<sup>3</sup>           | ✅                                     | 🛑                         | 🛑                                  |
 | Stale While Revalidate                       | ✅                                     | ✅                         | 🛑                                  |
 | Stale Time Configuration                     | ✅                                     | 🛑                         | 🛑                                  |
 | Window Focus Refetching                      | ✅                                     | ✅                         | 🛑                                  |
 | Network Status Refetching                    | ✅                                     | ✅                         | ✅                                  |
-| Automatic Refetch after Mutation<sup>3</sup> | 🔶                                     | 🔶                         | ✅                                  |
+| Automatic Refetch after Mutation<sup>4</sup> | 🔶                                     | 🔶                         | ✅                                  |
 | Cache Dehydration/Rehydration                | ✅                                     | 🛑                         | ✅                                  |
 | React Suspense (Experimental)                | ✅                                     | ✅                         | 🛑                                  |
 
 ### Notes
 
 > **<sup>1</sup> Lagged / "Lazy" Queries** - React Query provides a way to continue to see an existing query's data while the next query loads (similar to the same UX that suspense will soon provide natively). This is extremely important when writing pagination UIs or infinite loading UIs where you do not want to show a hard loading state whenever a new query is requested. Other libraries do not have this capability and render a hard loading state for the new query (unless it has been prefetched), while the new query loads.
 
-> **<sup>2</sup> Partial query matching** - Because React Query uses deterministic query key serialization, this allows you to manipulate variable groups of queries without having to know each individual query-key that you want to match, eg. you can refetch every query that starts with `todos` in its key, regardless of variables, or you can target specific queries with (or without) variables or nested properties, and even use a filter function to only match queries that pass your specific conditions.
+> **<sup>2</sup> Render Optimization** - React Query has excellent rendering performance. It will only re-render your components when a query is updated. For example because it has new data, or to indicate it is fetching. React Query also batches updates together to make sure your application only re-renders once when multiple components are using the same query. If you are only interested in the `data` or `error` properties, you can reduce the number of renders even more by setting `notifyOnStatusChange` to `false`.
 
-> **<sup>3</sup> Automatic Refetch after Mutation** - For truly automatic refetching to happen after a mutation occurs, a schema is necessary (like the one graphQL provides) along with heuristics that help the library know how to identify individual entities and entities types in that schema.
+> **<sup>3</sup> Partial query matching** - Because React Query uses deterministic query key serialization, this allows you to manipulate variable groups of queries without having to know each individual query-key that you want to match, eg. you can refetch every query that starts with `todos` in its key, regardless of variables, or you can target specific queries with (or without) variables or nested properties, and even use a filter function to only match queries that pass your specific conditions.
+
+> **<sup>4</sup> Automatic Refetch after Mutation** - For truly automatic refetching to happen after a mutation occurs, a schema is necessary (like the one graphQL provides) along with heuristics that help the library know how to identify individual entities and entities types in that schema.
 
 [swr]: https://github.com/vercel/swr
 [apollo]: https://github.com/apollographql/apollo-client

rollup.config.js

@@ -7,11 +7,12 @@ import commonJS from 'rollup-plugin-commonjs'
 import visualizer from 'rollup-plugin-visualizer'
 import replace from '@rollup/plugin-replace'
 
-const external = ['react']
+const external = ['react', 'react-dom']
 const hydrationExternal = [...external, 'react-query']
 
 const globals = {
   react: 'React',
+  'react-dom': 'ReactDOM',
 }
 const hydrationGlobals = {
   ...globals,

src/core/index.ts

@@ -7,7 +7,13 @@ export {
 } from './queryCache'
 export { setFocusHandler } from './setFocusHandler'
 export { setOnlineHandler } from './setOnlineHandler'
-export { CancelledError, isCancelledError, isError, setConsole } from './utils'
+export {
+  CancelledError,
+  isCancelledError,
+  isError,
+  setConsole,
+  setBatchedUpdates,
+} from './utils'
 
 // Types
 export * from './types'

src/core/notifyManager.ts

@@ -0,0 +1,56 @@
+import { getBatchedUpdates, scheduleMicrotask } from './utils'
+
+// TYPES
+
+type NotifyCallback = () => void
+
+// CLASS
+
+export class NotifyManager {
+  private queue: NotifyCallback[]
+  private transactions: number
+
+  constructor() {
+    this.queue = []
+    this.transactions = 0
+  }
+
+  batch<T>(callback: () => T): T {
+    this.transactions++
+    const result = callback()
+    this.transactions--
+    if (!this.transactions) {
+      this.flush()
+    }
+    return result
+  }
+
+  schedule(notify: NotifyCallback): void {
+    if (this.transactions) {
+      this.queue.push(notify)
+    } else {
+      scheduleMicrotask(() => {
+        notify()
+      })
+    }
+  }
+
+  flush(): void {
+    const queue = this.queue
+    this.queue = []
+    if (queue.length) {
+      scheduleMicrotask(() => {
+        const batchedUpdates = getBatchedUpdates()
+        batchedUpdates(() => {
+          queue.forEach(notify => {
+            notify()
+          })
+        })
+      })
+    }
+  }
+}
+
+// SINGLETON
+
+export const notifyManager = new NotifyManager()

src/core/query.ts

@@ -23,6 +23,7 @@ import {
 } from './types'
 import type { QueryCache } from './queryCache'
 import { QueryObserver, UpdateListener } from './queryObserver'
+import { notifyManager } from './notifyManager'
 
 // TYPES
 
@@ -134,11 +135,13 @@ export class Query<TResult, TError> {
   private dispatch(action: Action<TResult, TError>): void {
     this.state = queryReducer(this.state, action)
 
-    this.observers.forEach(observer => {
-      observer.onQueryUpdate(action)
-    })
+    notifyManager.batch(() => {
+      this.observers.forEach(observer => {
+        observer.onQueryUpdate(action)
+      })
 
-    this.queryCache.notifyGlobalListeners(this)
+      this.queryCache.notifyGlobalListeners(this)
+    })
   }
 
   private scheduleGc(): void {

src/core/queryCache.ts

@@ -18,6 +18,7 @@ import {
   TypedQueryFunctionArgs,
   ResolvedQueryConfig,
 } from './types'
+import { notifyManager } from './notifyManager'
 
 // TYPES
 
@@ -94,8 +95,12 @@ export class QueryCache {
       0
     )
 
-    this.globalListeners.forEach(listener => {
-      listener(this, query)
+    notifyManager.batch(() => {
+      this.globalListeners.forEach(listener => {
+        notifyManager.schedule(() => {
+          listener(this, query)
+        })
+      })
     })
   }
 
@@ -209,8 +214,10 @@ export class QueryCache {
   ): Promise<Query<unknown, unknown>[]> {
     const queries = this.getQueries(predicate, options)
 
-    queries.forEach(query => {
-      query.invalidate()
+    notifyManager.batch(() => {
+      queries.forEach(query => {
+        query.invalidate()
+      })
     })
 
     const { refetchActive = true, refetchInactive = false } = options || {}
@@ -245,14 +252,16 @@ export class QueryCache {
   ): Promise<Query<unknown, unknown>[]> {
     const promises: Promise<Query<unknown, unknown>>[] = []
 
-    this.getQueries(predicate, options).forEach(query => {
-      let promise = query.fetch().then(() => query)
+    notifyManager.batch(() => {
+      this.getQueries(predicate, options).forEach(query => {
+        let promise = query.fetch().then(() => query)
 
-      if (!options?.throwOnError) {
-        promise = promise.catch(() => query)
-      }
+        if (!options?.throwOnError) {
+          promise = promise.catch(() => query)
+        }
 
-      promises.push(promise)
+        promises.push(promise)
+      })
     })
 
     return Promise.all(promises)
@@ -398,9 +407,11 @@ export function makeQueryCache(config?: QueryCacheConfig) {
 
 export function onVisibilityOrOnlineChange(type: 'focus' | 'online') {
   if (isDocumentVisible() && isOnline()) {
-    queryCaches.forEach(queryCache => {
-      queryCache.getQueries().forEach(query => {
-        query.onInteraction(type)
+    notifyManager.batch(() => {
+      queryCaches.forEach(queryCache => {
+        queryCache.getQueries().forEach(query => {
+          query.onInteraction(type)
+        })
       })
     })
   }

src/core/queryObserver.ts

@@ -5,6 +5,7 @@ import {
   isValidTimeout,
   noop,
 } from './utils'
+import { notifyManager } from './notifyManager'
 import type { QueryResult, ResolvedQueryConfig } from './types'
 import type { Query, Action, FetchMoreOptions, RefetchOptions } from './query'
 
@@ -149,8 +150,15 @@ export class QueryObserver<TResult, TError> {
     }
   }
 
-  private notify(): void {
-    this.listener?.(this.currentResult)
+  private notify(global?: boolean): void {
+    notifyManager.batch(() => {
+      notifyManager.schedule(() => {
+        this.listener?.(this.currentResult)
+      })
+      if (global) {
+        this.config.queryCache.notifyGlobalListeners(this.currentQuery)
+      }
+    })
   }
 
   private updateStaleTimeout(): void {
@@ -172,8 +180,7 @@ export class QueryObserver<TResult, TError> {
       if (!this.isStale) {
         this.isStale = true
         this.updateResult()
-        this.notify()
-        this.config.queryCache.notifyGlobalListeners(this.currentQuery)
+        this.notify(true)
       }
     }, timeout)
   }
@@ -221,20 +228,19 @@ export class QueryObserver<TResult, TError> {
   }
 
   private updateResult(): void {
-    const { currentQuery, previousQueryResult, config } = this
-    const { state } = currentQuery
+    const { state } = this.currentQuery
     let { data, status, updatedAt } = state
     let isPreviousData = false
 
     // Keep previous data if needed
     if (
-      config.keepPreviousData &&
+      this.config.keepPreviousData &&
       state.isInitialData &&
-      previousQueryResult?.isSuccess
+      this.previousQueryResult?.isSuccess
     ) {
-      data = previousQueryResult.data
-      updatedAt = previousQueryResult.updatedAt
-      status = previousQueryResult.status
+      data = this.previousQueryResult.data
+      updatedAt = this.previousQueryResult.updatedAt
+      status = this.previousQueryResult.status
       isPreviousData = true
     }
 

src/core/tests/queryCache.test.tsx

@@ -5,7 +5,7 @@ import {
   mockConsoleError,
   mockNavigatorOnLine,
 } from '../../react/tests/utils'
-import { queryCache as defaultQueryCache, QueryCache } from '..'
+import { QueryCache, queryCache as defaultQueryCache } from '../..'
 import { isCancelledError, isError } from '../utils'
 
 describe('queryCache', () => {
@@ -379,14 +379,15 @@ describe('queryCache', () => {
       expect(query.queryCache).toBe(queryCache)
     })
 
-    test('notifyGlobalListeners passes the same instance', () => {
+    test('notifyGlobalListeners passes the same instance', async () => {
       const key = queryKey()
 
       const queryCache = new QueryCache()
       const subscriber = jest.fn()
       const unsubscribe = queryCache.subscribe(subscriber)
       const query = queryCache.buildQuery(key)
       query.setData('foo')
+      await sleep(1)
       expect(subscriber).toHaveBeenCalledWith(queryCache, query)
 
       unsubscribe()

src/core/tests/utils.test.tsx

@@ -1,5 +1,5 @@
 import { replaceEqualDeep, deepIncludes, isPlainObject } from '../utils'
-import { setConsole, queryCache } from '..'
+import { setConsole, queryCache } from '../..'
 import { queryKey } from '../../react/tests/utils'
 
 describe('core/utils', () => {

src/core/utils.ts

@@ -250,3 +250,34 @@ export function createSetHandler(fn: () => void) {
     removePreviousHandler = callback(fn)
   }
 }
+
+/**
+ * Schedules a microtask.
+ * This can be useful to schedule state updates after rendering.
+ */
+export function scheduleMicrotask(callback: () => void): void {
+  Promise.resolve()
+    .then(callback)
+    .catch(error =>
+      setTimeout(() => {
+        throw error
+      })
+    )
+}
+
+type BatchUpdateFunction = (callback: () => void) => void
+
+// Default to a dummy "batch" implementation that just runs the callback
+let batchedUpdates: BatchUpdateFunction = (callback: () => void) => {
+  callback()
+}
+
+// Allow injecting another batching function later
+export function setBatchedUpdates(fn: BatchUpdateFunction) {
+  batchedUpdates = fn
+}
+
+// Supply a getter just to skip dealing with ESM bindings
+export function getBatchedUpdates(): BatchUpdateFunction {
+  return batchedUpdates
+}

src/index.ts

@@ -1,2 +1,6 @@
+import { setBatchedUpdates } from './core/index'
+import { unstable_batchedUpdates } from './react/reactBatchedUpdates'
+setBatchedUpdates(unstable_batchedUpdates)
+
 export * from './core/index'
 export * from './react/index'

src/react/reactBatchedUpdates.native.ts

@@ -0,0 +1,3 @@
+// @ts-ignore
+import { unstable_batchedUpdates } from 'react-native'
+export { unstable_batchedUpdates }

src/react/reactBatchedUpdates.ts

@@ -0,0 +1,2 @@
+import ReactDOM from 'react-dom'
+export const unstable_batchedUpdates = ReactDOM.unstable_batchedUpdates

src/react/tests/ReactQueryCacheProvider.test.tsx

@@ -2,8 +2,13 @@ import React, { useEffect } from 'react'
 import { render, waitFor } from '@testing-library/react'
 
 import { sleep, queryKey } from './utils'
-import { ReactQueryCacheProvider, useQuery, useQueryCache } from '..'
-import { queryCache, QueryCache } from '../../core'
+import {
+  ReactQueryCacheProvider,
+  useQuery,
+  useQueryCache,
+  queryCache,
+  QueryCache,
+} from '../..'
 
 describe('ReactQueryCacheProvider', () => {
   test('when not used, falls back to global cache', async () => {

src/react/tests/ReactQueryConfigProvider.test.tsx

@@ -2,8 +2,7 @@ import React, { useState } from 'react'
 import { act, fireEvent, render, waitFor } from '@testing-library/react'
 
 import { sleep, queryKey } from './utils'
-import { ReactQueryConfigProvider, useQuery } from '..'
-import { queryCache } from '../../core'
+import { ReactQueryConfigProvider, useQuery, queryCache } from '../..'
 
 describe('ReactQueryConfigProvider', () => {
   // // See https://github.com/tannerlinsley/react-query/issues/105