Lazy useQuery and imperative paradigm

[incepter]

Hello all,

While having a discussion with @TkDodo on twitter, we evoked the possibility to define lazy queries that can be fired from event handlers without relying on additional state variables in the developer land. ie:

const {run} = useQuery(_, __, { lazy: true });


// later
<input onChange={e => run(e.target.value)} />

For the library, it will just not run the fetcher and delay it until the decision comes from an event handler.

The difference between lazy and enabled is:

• by enabled you put a condition that should work only when lazy is false, meaning at every dependency change, you check again if the condition in enabled is truthy and later you should keep track of enabled if it transition from false to true. And you can't change this condition unless to perform a complete render.
• by lazy you tell the library: Please don't fire automatically at all, the user will control this. It is similar to mutation, but mentally, it is a query that you can run from everywhere in your app and gives you data to display.

For example, directly searching when the user types in drop down, or a search list that starts with empty results... and so on.

The run function then will pass its arguments as args property in the argv that the query function receives.

Here is a demonstration of what the API that I advice for:

async function fetchUser(props: ProducerProps<User>): Promise<User> {
  const controller = new AbortController();
  props.onAbort(() => controller.abort());

  const [userId] = props.args;

  const usersResponse = await API.get("/users/" + userId, { signal: controller.signal });
  return usersResponse.data;
}

// Component
const { run, state } = useAsyncState({
    lazy: true,
    producer: fetchUser,
    runEffect: "debounce",
    skipPendingDelayMs: 200,
    runEffectDurationMs: 300,
    cacheConfig: {
      enabled: true,
      hash: (args) => `user-${args?.[0]}`,
      getDeadline: (s) => s.data.maxAge || 5_000
    }
  });
const { status, data, props } = state;

return (
    <div className="App">
      <input onChange={(e) => run(e.target.value)} />
      <h3>Status is: {status}</h3>
      {status === "success" && (...)}
      {status === "error" && (...)}
    </div>
  );

Please note that I may contribute to the proposed features as well.

Best regards.

[incepter]

@TkDodo @tannerlinsley any thoughts on this ?

[TkDodo]

I'm not sure how we would technically do this right now. The queryKey would need to become a function that gets arguments passed from run into it, because we'd want separate caching per arguments. Maybe it would need to be a separate hook or so.

In most of the cases I have encountered, people have the value of the input in state already. The moment you want to do anything else with the search input, you need to store it somewhere. At that point, you can declaratively read it. For search, putting it in the url is ideal. Something like this codesandbox: https://codesandbox.io/s/react-query-url-filtering-h0ikw?file=/src/App.tsx

[incepter]

Thanks for your reply Dominik, I appreciate it. I ll give it a try once i get some free time for sure to see how we can do this.

[allicanseenow]

@TkDodo So I suppose there's no way to use useQuery imperatively then? A useful scenarios would be if a component has multiple different, unrelated lazy queries. Making them imperative saves you the effort of not having to create a state to act as a key for each query.

And for the scenario: when I click a button in a component, the component will need to fetch data either from the API or the cache if the key hasn't changed, I will need to send an event only once after the API finishes (whether with the new data or the cached one). Imagine this scenario with useMutation from the docs but instead of useMutation, now I have useQuery instead with the benefit of both onSuccess and onError:

useMutation({
  mutationFn: addTodo,
  onSuccess: (data, variables, context) => {
    // I will fire first
  },
  onError: (error, variables, context) => {
    // I will fire first
  },
  onSettled: (data, error, variables, context) => {
    // I will fire first
  },
})

Currently, there's a way to do this is to put the data of the useQuery in a useEffect and trigger an event once the data changes, but it's not ideal as there's no way to make sure the logic inside useEffect only run due to the button click.

I wonder if there's a way to do this?

[TkDodo]

So I suppose there's no way to use useQuery imperatively then?

There is for sure.

Making them imperative saves you the effort of not having to create a state to act as a key for each query.

Can you show a concrete example of this please? I haven’t seen many situations where state should only be available inside an event handler, but isn’t used anywhere on the screen. My usual example is a filter form: It might have state internally, or it might be fully uncontrolled, but as soon as you click the Apply button, it becomes “applied state” that should be stored somewhere. The URL is a very good place for that because it gives you sharable links for free.

And for the scenario

You can always call: const data = await queryClient.fetchQuery(...) in your event handler. It respects staleTime so it won’t fetch if you have fresh data. Then, you can do whatever you want afterwards, and errors can be handled in try/catch. There are few cases where this is a good idea - async validations of a form field come to mind. In most cases where you think you want this, it’s an architectural or a mindset problem that’s very often better solved with declarative fetching.

[allicanseenow]

Thanks for the quick response. I didn't expect to receive it that quickly.

I suppose an example might be a dashboard (like swagger for example) where I put like dozens of buttons, each will call an API and then show a toaster once the API finishes. I feel like the design would be so much more simple if I can just write an inline function in each button like

<Button onClick={() => query.asyncQuery(....).then(showToaster)}/>

I didn't think about using queryClient as I only created one instance of it and pass it to the . Does that mean I will need to use a React context to access it in a nested component, or I can just create the queryClient in a separate file and import it everywhere?

[TkDodo]

useQueryClient can give you the queryClient. It already uses context - the QueryClientProvider

[TkDodo]

https://tkdodo.eu/blog/react-query-fa-qs#why-should-i-usequeryclient

[allicanseenow]

Thanks. I'll have a look at that.