feat: allow custom function for structuralSharing (#3868)

richsilv · web-flow · commit f9ebf9aaae59 · 2022-08-16T10:17:18.000+02:00
diff --git a/docs/guides/important-defaults.md b/docs/guides/important-defaults.md
@@ -30,12 +30,11 @@ If you see a refetch that you are not expecting, it is likely because you just f
 
 - 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. If this concept sounds foreign, then don't worry about it! 99.9% of the time you will not need to disable this and it makes your app more performant at zero cost to you.
 
-> 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`.
+> 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` or provide your own custom function as `config.structuralSharing` to compute a value from the old and new responses, retaining references as required.
 
 ## Further Reading
 
 Have a look at the following articles from our Community Resources for further explanations of the defaults:
 
 - [Practical React Query](../community/tkdodos-blog#1-practical-react-query)
 - [React Query as a State Manager](../community/tkdodos-blog#10-react-query-as-a-state-manager)
-
diff --git a/docs/reference/useQuery.md b/docs/reference/useQuery.md
@@ -178,10 +178,11 @@ const result = useQuery({
 - `isDataEqual: (oldData: TData | undefined, newData: TData) => boolean`
   - Optional
   - This function should return boolean indicating whether to use previous `data` (`true`) or new data (`false`) as a resolved data for the query.
-- `structuralSharing: boolean`
+- `structuralSharing: boolean | ((oldData: TData | undefined, newData: TData) => TData)`
   - Optional
   - Defaults to `true`
   - If set to `false`, structural sharing between query results will be disabled.
+  - If set to a function, the old and new data values will be passed through this function, which should combine them into resolved data for the query. This way, you can retain references from the old data to improve performance even when that data contains non-serializable values.
 - `useErrorBoundary: undefined | boolean | (error: TError, query: Query) => boolean`
   - Defaults to the global query config's `useErrorBoundary` value, which is `undefined`
   - Set this to `true` if you want errors to be thrown in the render phase and propagate to the nearest error boundary
diff --git a/packages/query-core/src/tests/queryClient.test.tsx b/packages/query-core/src/tests/queryClient.test.tsx
@@ -13,6 +13,7 @@ import {
   QueryClient,
   QueryFunction,
   QueryObserver,
+  QueryObserverOptions,
 } from '..'
 import { focusManager, onlineManager } from '..'
 
@@ -357,6 +358,38 @@ describe('queryClient', () => {
       expect(queryCache.find(key)!.state.data).toBe(newData)
     })
 
+    test('should apply a custom structuralSharing function when provided', () => {
+      const key = queryKey()
+
+      const queryObserverOptions = {
+        structuralSharing: (
+          prevData: { value: Date } | undefined,
+          newData: { value: Date },
+        ) => {
+          if (!prevData) {
+            return newData
+          }
+          return newData.value.getTime() === prevData.value.getTime()
+            ? prevData
+            : newData
+        },
+      } as QueryObserverOptions
+
+      queryClient.setDefaultOptions({ queries: queryObserverOptions })
+
+      const oldData = { value: new Date(2022, 6, 19) }
+      const newData = { value: new Date(2022, 6, 19) }
+      queryClient.setQueryData(key, oldData)
+      queryClient.setQueryData(key, newData)
+
+      expect(queryCache.find(key)!.state.data).toBe(oldData)
+
+      const distinctData = { value: new Date(2021, 11, 25) }
+      queryClient.setQueryData(key, distinctData)
+
+      expect(queryCache.find(key)!.state.data).toBe(distinctData)
+    })
+
     test('should not set isFetching to false', async () => {
       const key = queryKey()
       queryClient.prefetchQuery(key, async () => {
diff --git a/packages/query-core/src/types.ts b/packages/query-core/src/types.ts
@@ -76,9 +76,12 @@ export interface QueryOptions<
   behavior?: QueryBehavior<TQueryFnData, TError, TData>
   /**
    * Set this to `false` to disable structural sharing between query results.
+   * Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic.
    * Defaults to `true`.
    */
-  structuralSharing?: boolean
+  structuralSharing?:
+    | boolean
+    | ((oldData: TData | undefined, newData: TData) => TData)
   /**
    * This function can be set to automatically get the previous cursor for infinite queries.
    * The result will also be used to determine the value of `hasPreviousPage`.
diff --git a/packages/query-core/src/utils.ts b/packages/query-core/src/utils.ts
@@ -427,6 +427,8 @@ export function replaceData<
   // Use prev data if an isDataEqual function is defined and returns `true`
   if (options.isDataEqual?.(prevData, data)) {
     return prevData as TData
+  } else if (typeof options.structuralSharing === 'function') {
+    return options.structuralSharing(prevData, data)
   } else if (options.structuralSharing !== false) {
     // Structurally share data between prev and new data if needed
     return replaceEqualDeep(prevData, data)
