feat(query-core): include current query as a placeholder data function param

Signed-off-by: nicole mikołajczyk <git@mkljczk.pl>

Author: mkljczk

.changeset/long-bars-lay.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/query-core': minor
+---
+
+feat(query-core): include current query as a placeholder data function param

docs/framework/react/reference/useQuery.md

@@ -155,7 +155,7 @@ const {
 - `initialDataUpdatedAt: number | (() => number | undefined)`
   - Optional
   - If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated.
-- `placeholderData: TData | (previousValue: TData | undefined, previousQuery: Query | undefined) => TData`
+- `placeholderData: TData | (previousValue: TData | undefined, previousQuery: Query | undefined, currentQuery: Query) => TData`
   - Optional
   - If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `pending` state.
   - `placeholderData` is **not persisted** to the cache

docs/framework/solid/reference/useQuery.md

@@ -204,7 +204,7 @@ function App() {
     - Optional
     - This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache.
     - The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, wrap the function in `useCallback`.
-  - ##### `placeholderData: TData | (previousValue: TData | undefined; previousQuery: Query | undefined,) => TData`
+  - ##### `placeholderData: TData | (previousValue: TData | undefined, previousQuery: Query | undefined, currentQuery: Query) => TData`
     - Optional
     - If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `pending` state.
     - `placeholderData` is **not persisted** to the cache

packages/query-core/src/__tests__/queryObserver.test.tsx

@@ -1066,6 +1066,36 @@ describe('queryObserver', () => {
     expect(selectCount).toBe(3)
   })
 
+  test('should pass the current query to placeholderData function', () => {
+    const testQueryKey = queryKey()
+
+    const placeholderDataSpy = vi.fn(
+      (_: unknown, __: unknown, ___: unknown) => undefined,
+    )
+
+    const queryClient2 = new QueryClient({
+      defaultOptions: {
+        queries: {
+          placeholderData: placeholderDataSpy,
+        },
+      },
+    })
+
+    new QueryObserver(queryClient2, {
+      queryKey: testQueryKey,
+      queryFn: () => Promise.resolve(),
+    })
+
+    expect(placeholderDataSpy).toHaveBeenCalledTimes(1)
+    expect(placeholderDataSpy).toHaveBeenCalledWith(
+      undefined,
+      undefined,
+      expect.objectContaining({ queryKey: testQueryKey }),
+    )
+
+    queryClient2.clear()
+  })
+
   test('should use cached selectResult when switching between queries and placeholderData returns previousData', async () => {
     const results: Array<QueryObserverResult> = []
 

packages/query-core/src/queryObserver.ts

@@ -505,10 +505,11 @@ export class QueryObserver<
         placeholderData =
           typeof options.placeholderData === 'function'
             ? (
-                options.placeholderData as unknown as PlaceholderDataFunction<TQueryData>
+                options.placeholderData as unknown as PlaceholderDataFunction<TQueryData, TError>
               )(
                 this.#lastQueryWithDefinedData?.state.data,
                 this.#lastQueryWithDefinedData as any,
+                query as any,
               )
             : options.placeholderData
       }

packages/query-core/src/types.ts

@@ -176,6 +176,7 @@ export type PlaceholderDataFunction<
 > = (
   previousData: TQueryData | undefined,
   previousQuery: Query<TQueryFnData, TError, TQueryData, TQueryKey> | undefined,
+  currentQuery: Query<TQueryFnData, TError, TQueryData, TQueryKey>,
 ) => TQueryData | undefined
 
 export type QueriesPlaceholderDataFunction<TQueryData> = (