feat(query-core): add structuralSharing option to useQueries

.changeset/silver-coins-mix.md

@@ -0,0 +1,11 @@
+---
+'@tanstack/angular-query-experimental': minor
+'@tanstack/svelte-query': minor
+'@tanstack/react-query': minor
+'@tanstack/preact-query': minor
+'@tanstack/solid-query': minor
+'@tanstack/query-core': minor
+'@tanstack/vue-query': minor
+---
+
+feat(query-core): Allow disabling structuralSharing for useQueries.

docs/framework/react/reference/useQueries.md

@@ -24,6 +24,12 @@ The `useQueries` hook accepts an options object with a **queries** key whose val
   - Use this to provide a custom QueryClient. Otherwise, the one from the nearest context will be used.
 - `combine?: (result: UseQueriesResults) => TCombinedResult`
   - Use this to combine the results of the queries into a single value.
+- `structuralSharing?: boolean | ((oldData: unknown | undefined, newData: unknown) => unknown)`
+  - Optional
+  - Defaults to `true`.
+  - Only applies when `combine` is provided.
+  - 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.
 
 > Having the same query key more than once in the array of query objects may cause some data to be shared between queries. To avoid this, consider de-duplicating the queries and map the results back to the desired structure.
 
@@ -37,7 +43,7 @@ The `useQueries` hook returns an array with all the query results. The order ret
 
 ## Combine
 
-If you want to combine `data` (or other Query information) from the results into a single value, you can use the `combine` option. The result will be structurally shared to be as referentially stable as possible.
+If you want to combine `data` (or other Query information) from the results into a single value, you can use the `combine` option. The result will be structurally shared to be as referentially stable as possible. If you want to disable structural sharing for the combined result, you can set the `structuralSharing` option to `false`, or provide a custom function to implement your own structural sharing logic.
 
 ```tsx
 const ids = [1, 2, 3]

packages/angular-query-experimental/src/inject-queries.ts

@@ -211,6 +211,15 @@ export interface InjectQueriesOptions<
         ...{ [K in keyof T]: GetCreateQueryOptionsForCreateQueries<T[K]> },
       ]
   combine?: (result: QueriesResults<T>) => TCombinedResult
+  /**
+   * 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.
+   * Only applies when `combine` is provided.
+   * Defaults to `true`.
+   */
+  structuralSharing?:
+    | boolean
+    | ((oldData: unknown | undefined, newData: unknown) => unknown)
 }
 
 /**
@@ -271,6 +280,8 @@ export function injectQueries<
       observerSignal().getOptimisticResult(
         defaultedQueries(),
         (optionsSignal() as QueriesObserverOptions<TCombinedResult>).combine,
+        (optionsSignal() as QueriesObserverOptions<TCombinedResult>)
+          .structuralSharing,
       ),
     )
 

packages/preact-query/src/useQueries.ts

@@ -217,6 +217,15 @@ export function useQueries<
       | readonly [...QueriesOptions<T>]
       | readonly [...{ [K in keyof T]: GetUseQueryOptionsForUseQueries<T[K]> }]
     combine?: (result: QueriesResults<T>) => TCombinedResult
+    /**
+     * 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.
+     * Only applies when `combine` is provided.
+     * Defaults to `true`.
+     */
+    structuralSharing?:
+      | boolean
+      | ((oldData: unknown | undefined, newData: unknown) => unknown)
     subscribed?: boolean
   },
   queryClient?: QueryClient,
@@ -263,6 +272,7 @@ export function useQueries<
     observer.getOptimisticResult(
       defaultedQueries,
       (options as QueriesObserverOptions<TCombinedResult>).combine,
+      options.structuralSharing,
     )
 
   const shouldSubscribe = !isRestoring && options.subscribed !== false