Adding Support for Custom Parameter Injection into QueryFunctionContext

[kj455]

Feature Request

Adding a mechanism to support the Dependency Injection (DI) of arbitrary values into QueryFunctionContext.

Background and Current Situation

As of now, the queryFn argument (QueryFunctionContext) supports only the following four elements:

• queryKey
• pageParam
• signal
• meta

I propose to extend this support to allow end-users to add arbitrary values, thereby facilitating a more flexible usage of the QueryFunctionContext.

Detailed Proposal

My current idea is to enable this through the Dependency Injection (DI) of these values at the time of creating the QueryClient, as illustrated below:

const queryClient = new QueryClient({
  ...
  extraArgument: { /** inject something useful here */ } 
})

This mechanism would resemble the withExtraArgument function utilized in redux-thunk.

• Reference to Redux Thunk's withExtraArgument)

Motivation

Implementing the above proposal would facilitate easier writing of queryFn tests. Although queryFn generally involves API requests, which usually result in the following type of code:

// CURRENT
// queryFn
const fetchTodoList = () => {
  const { data } = api.get('/todos'); // api refers to any http client of your preference.
  return data
}

// usecase
const { data } = useQuery({
  queryKey: ['todo', 'list'],
  queryFn: fetchTodoList
})

// test
test('fetchTodoList', async () => {
  const api = { get: jest.fn() }
  jest.mock('path/to/api', () => api); // you have to mock http client...

  await fetchTodoList();

  expect(api.get).toHaveBeenCalledWith('/todos')
})

To test fetchTodoList, one needs to employ jest.mock to mock the HTTP client since it's used directly, making the tests prone to breaking. Hence, there is a desire to write tests using DI instead of module mocking.

If the proposed DI into QueryFunctionContext becomes feasible, it would substantially simplify testing:

// PROPOSED
// init
const queryClient = new QueryClient({
  extraArgument: { api } // inject http client
})

// queryFn
const fetchTodoList = ({ api }) => {
  const { data } = api.get('/todos'); // no need to api directly!!!
  return data
}

// usecase
const { data } = useQuery({
  queryKey: ['todo', 'list'],
  queryFn: fetchTodoList
})

// test
test('fetchTodoList', async () => {
  const api = { get: jest.fn() }

  await fetchTodoList({ api });  // no need to mock api!!

  expect(api.get).toHaveBeenCalledWith('/todos')
})

Conclusion

I believe that the addition of this feature to the QueryFunctionContext would be highly beneficial. I would appreciate similar support in mutations as well. I am open to providing further details if needed, and if the technical complexity isn't high, I am motivated to contribute to its development.

I eagerly await your feedback and am open to discussing the technical feasibility and implications of this feature request further. Any suggestions or opinions on this feature request would be highly valued.

[TkDodo]

I propose to extend this support to allow end-users to add arbitrary values, thereby facilitating a more flexible usage of the

I would say this is exactly what meta is for 😅 . From the docs:

meta: Record<string, unknown>
Optional
If set, stores additional information on the query cache entry that can be used as needed. It will be accessible wherever the query is available, and is also part of the QueryFunctionContext provided to the queryFn.

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      meta: {
       api // inject http client
     }
    }
  }
})

[TkDodo]

generally, for what you want, my suggestion would rather be to create an <ApiProvider> and inject your api separately, and read from that in the queryFn as well as in the mutationFn.

[kj455]

Thank you for the swift advice.
Indeed, creating an <ApiProvider> seems like a promising approach. Thank you for offering such a valuable perspective!

[kj455]

@TkDodo
I apologize for asking another question.

I understand that injecting values such as api into defaultOptions.queries.meta would make them available in the queryFn arguments of all Queries.
However, if we set unique values in meta for individual Queries (like values for global error handling), it seems that the meta would be overridden, erasing the originally set values(e.g. api).

In this case, it seems feasible to solve this by obtaining the default meta using queryClient.getDefaultOptions and merging it with the unique meta values, but I wonder if there are other alternatives?

const queryClient = useQueryClient();
const { data } = useQuery({
  queryFn: ({ meta: { api } }) => {...},
  meta: {
    ...queryClient.getDefaultOptions().meta,
    errorMessage: 'failed to fetch todos' // for global error
  }
})

If the above method is the most straightforward approach, it makes me feel that utilizing the suggested <ApiProvider> might be a more intuitive option.

[TkDodo]

yeah you'd need to merge like you've shown. I personally wouldn't set meta on a global level

[kj455]

I'm also leaning towards not setting the meta globally. Thank you!!