Provide a context object (client, queryKey, meta) to the placeholderData function

[RodolfoSilva]

Summary

placeholderData is the only option that produces data without access to the QueryClient. I'd like to propose passing it a context argument, matching what queryFn and the mutation callbacks already receive.

Current signature

export type PlaceholderDataFunction
  TQueryFnData = unknown,
  TError = DefaultError,
  TQueryData = TQueryFnData,
  TQueryKey extends QueryKey = QueryKey,
> = (
  previousData: TQueryData | undefined,
  previousQuery: Query<TQueryFnData, TError, TQueryData, TQueryKey> | undefined,
) => TQueryData | undefined

Proposal

export type PlaceholderDataContext<TQueryKey extends QueryKey = QueryKey> = {
  client: QueryClient
  queryKey: TQueryKey
  meta: QueryMeta | undefined
}

export type PlaceholderDataFunction<...> = (
  previousData: TQueryData | undefined,
  previousQuery: Query<...> | undefined,
  context: PlaceholderDataContext<TQueryKey>,
) => TQueryData | undefined

The parameter is added at the end, so existing code keeps working.

Why

queryFn receives QueryFunctionContext, which carries client, queryKey, signal and meta. mutationFn and every mutation callback received MutationFunctionContext (client, meta, mutationKey) in #9615, shipped in v5.89.0. placeholderData was left out of that convergence.

The practical consequence is that the "placeholder data from cache" example in the docs can only live inside a component:

function BlogPost({ blogPostId }) {
  const queryClient = useQueryClient()

  const result = useQuery({
    queryKey: ['blogPost', blogPostId],
    queryFn: () => fetch(`/blogPosts/${blogPostId}`),
    placeholderData: () =>
      queryClient
        .getQueryData(['blogPosts'])
        ?.find((d) => d.id === blogPostId),
  })
}

That collides with the queryOptions pattern the docs recommend elsewhere. To move these options into a shared file today, the client has to be threaded in by hand:

export const blogPostOptions = (client: QueryClient, blogPostId: string) =>
  queryOptions({
    queryKey: ['blogPost', blogPostId],
    queryFn: () => fetchBlogPost(blogPostId),
    placeholderData: () =>
      client.getQueryData(['blogPosts'])?.find((d) => d.id === blogPostId),
  })

And that spreads. Every caller now needs a client just to build the options: components, prefetchQuery on the server, route loaders, tests. The queryFn sitting right next to it never asked for one. The options object also stops being a plain value, which makes it harder to reuse across adapters and to keep next to the rest of the query definition.

With a context argument, the factory depends only on its own arguments again:

export const blogPostOptions = (blogPostId: string) =>
  queryOptions({
    queryKey: ['blogPost', blogPostId],
    queryFn: () => fetchBlogPost(blogPostId),
    placeholderData: (_previousData, _previousQuery, { client }) =>
      client.getQueryData(['blogPosts'])?.find((d) => d.id === blogPostId),
  })

Why the existing parameters don't cover this

previousQuery is undefined on the first mount, which is exactly when you want to seed from another cache entry. When it is defined, the client sits in a private field (#client on Query), so there is no way to read it from there. The same applies to queryKey and meta.

#10427 is open and asks for the current query as a parameter for a related reason: a globally configured placeholderData has no way to know which key it is running for. One context object covers both cases and avoids adding another positional parameter later.

Implementation

The call site in QueryObserver#createResult already holds everything it needs:

placeholderData =
  typeof options.placeholderData === 'function'
    ? options.placeholderData(
        this.#lastQueryWithDefinedData?.state.data,
        this.#lastQueryWithDefinedData as any,
        {
          client: this.#client,
          queryKey: options.queryKey,
          meta: options.meta,
        },
      )
    : options.placeholderData

I can send a PR with tests and a changeset if this direction makes sense.

[TkDodo]

queryFn is the only one that receives a QueryFunctionContext, we can’t pass it everywhere because we don’t have the signal and consuming it opts you into query cancellation.

placeholderData is an observer specific property so it’s rarely among the shared query options. If you really want that, passing the queryClient in manually to a function is fine imo.