feat: add structural sharing configuration flag (TanStack#902)

Author: boschni

docs/src/pages/docs/api.md

@@ -33,6 +33,7 @@ const {
   refetchIntervalInBackground,
   queryFnParamsFilter,
   refetchOnMount,
+  structuralSharing,
   isDataEqual,
   onError,
   onSuccess,
@@ -125,6 +126,10 @@ const queryInfo = useQuery({
   - Optional
   - This function will filter the params that get passed to `queryFn`.
   - For example, you can filter out the first query key from the params by using `queryFnParamsFilter: args => args.slice(1)`.
+- `structuralSharing: Boolean`
+  - Optional
+  - Defaults to `true`
+  - If set to `false`, structural sharing between query results will be disabled.
 
 **Returns**
 

docs/src/pages/docs/guides/important-defaults.md

@@ -9,4 +9,4 @@ Out of the box, React Query is configured with **aggressive but sane** defaults.
 - Query results that become unused (all instances of the query are unmounted) will still be cached in case they are used again for a default of 5 minutes before they are garbage collected. To change this, you can alter the default `cacheTime` for queries to something other than `1000 * 60 * 5` milliseconds.
 - Stale queries will automatically be refetched in the background **when the browser window is refocused by the user**. You can disable this using the `refetchOnWindowFocus` option in queries or the global config.
 - Queries that fail will silently be retried **3 times, with exponential backoff delay** before capturing and displaying an error to the UI. To change this, you can alter the default `retry` and `retryDelay` options for queries to something other than `3` and the default exponential backoff function.
-- Query results by default are deep compared to detect if data has actually changed and if not, the data reference remains unchanged to better help with value stabilization with regards to useMemo and useCallback. The default deep compare function use here (`config.isDataEqual`) only supports comparing JSON-compatible primitives. If you are dealing with any non-json compatible values in your query responses OR are seeing performance issues with the deep compare function, you should probably disable it (`config.isDataEqual = () => false`) or customize it to better fit your needs.
+- Query results by default are structurally shared to detect if data has actually changed and if not, the data reference remains unchanged to better help with value stabilization with regards to useMemo and useCallback. Structural sharing only works with JSON-compatible values, any other value types will always be considered as changed. If you are seeing performance issues because of large responses for example, you can disable this feature with the `config.structuralSharing` flag. If you are dealing with non-JSON compatible values in your query responses and still want to detect if data has changed or not, you can define a data compare function with `config.isDataEqual`.

docs/src/pages/docs/typescript.md

@@ -5,18 +5,10 @@ title: TypeScript
 
 React Query is now written in **TypeScript** to make sure the library and your projects are type-safe!
 
-## Migration
-
-React Query is currently typed with an external type definition file, which unfortunately often gets out of sync with the actual code.
-
-This is one of the reasons why the library has been migrated to TypeScript.
-
-But before exposing the new types, we first want to get your feedback on it!
-
-Install the `tsnext` tag to get the latest React Query with the new types:
+Install the latest version to get React Query with the new types:
 
 ```sh
-npm install react-query@tsnext --save
+npm install react-query --save
 ```
 
 ## Changes

src/core/config.ts

@@ -57,6 +57,7 @@ export const DEFAULT_CONFIG: ReactQueryConfig = {
     cacheTime: 5 * 60 * 1000,
     refetchOnWindowFocus: true,
     refetchOnMount: true,
+    structuralSharing: true,
   },
 }
 

src/core/query.ts

@@ -289,8 +289,10 @@ export class Query<TResult, TError> {
     // Get the new data
     let data: TResult | undefined = functionalUpdate(updater, prevData)
 
-    // Structurally share data between prev and new data
-    data = replaceEqualDeep(prevData, data)
+    // Structurally share data between prev and new data if needed
+    if (this.config.structuralSharing) {
+      data = replaceEqualDeep(prevData, data)
+    }
 
     // Use prev data if an isDataEqual function is defined and returns `true`
     if (this.config.isDataEqual?.(prevData, data)) {

src/core/tests/queryCache.test.tsx

@@ -85,6 +85,28 @@ describe('queryCache', () => {
     ).rejects.toEqual(new Error('error'))
   })
 
+  test('prefetchQuery should return undefined when an error is thrown', async () => {
+    const key = queryKey()
+
+    const consoleMock = jest.spyOn(console, 'error')
+    consoleMock.mockImplementation(() => undefined)
+
+    const result = await defaultQueryCache.prefetchQuery(
+      key,
+      async () => {
+        throw new Error('error')
+      },
+      {
+        retry: false,
+      }
+    )
+
+    expect(result).toBeUndefined()
+    expect(consoleMock).toHaveBeenCalled()
+
+    consoleMock.mockRestore()
+  })
+
   test('should notify listeners when new query is added', async () => {
     const key = queryKey()
 

src/core/types.ts

@@ -57,6 +57,11 @@ export interface BaseQueryConfig<TResult, TError = unknown> {
   initialData?: TResult | InitialDataFunction<TResult>
   initialStale?: boolean | InitialStaleFunction
   infinite?: true
+  /**
+   * Set this to `false` to disable structural sharing between query results.
+   * Defaults to `true`.
+   */
+  structuralSharing?: boolean
 }
 
 export interface QueryObserverConfig<TResult, TError = unknown>