global and local onError callbacks related questions

[cloudcompute]

I have few questions, could you pl. answer them:

a. Is it possible to execute the onError both at a global and local level for a given query or mutation. For example, use global onError to display toast and local onError to handle local logic, for example navigate to this particular route if error occurs.

b. Is it possible to execute global onError conditionally, like I do not want to show a toast for some errors. I think it might be achieved by adding a boolean key/value in the 'meta' object and check if it is set to true, then only display toast. Right?

c. Here is an example that displays a toast locally:

const login = async ({ email, password }) => {
  // Make an asynchrounous call to the server
  ...
  onError: (err) {
    // Local error handling
    displayToast("error", "Authentication Failed", err.errorMessage);
  }
}

Now react-query also lets us display toasts at a global level indicating that some validation failed. Keeping this in view, I am looking for code something like this:

const queryClient = new QueryClient({
  queryCache: new QueryCache({
    onError: (error, query) => {
      // show error toasts if react-query's background fetch fails
      if (query.state.data !== undefined) {
        displayToast("error", "an appropriate title like... Server not reachable", "an appropriate error message")
      }
      // display error toast for ALL of our queries and mutations.. at a single place here meaning no local onError handler
      else {
        //title: Authentication Failed.. fetched from meta
        displayToast("error", title, error.message)
      }
    },
  }),
})

As of now, I don't know react-query much. So pl. confirm if the if/else logic is correct.

Is this pattern okay with you, or would you advise local onError handler for each query and mutation placed immediately after the server response in the local functions themselves?

d. In order to display toast for failed background queries, we are writing a global onError callback for "QueryCache". For the same reason, it needs to be written for MutationCache as well. Am I right?

[TkDodo]

a. Is it possible to execute the onError both at a global and local level for a given query or mutation. For example, use global onError to display toast and local onError to handle local logic, for example navigate to this particular route if error occurs.

if by global you man the onError callback on the queryCache then yes, because the queryCache callbacks always get executed. However, the onError specified under defaultOptions of the queryClient will be overwritten by specific handlers on useQuery because the defaultOptions are "fallbacks" / "defaults".

b. Is it possible to execute global onError conditionally, like I do not want to show a toast for some errors. I think it might be achieved by adding a boolean key/value in the 'meta' object and check if it is set to true, then only display toast. Right?

yes, exactly. If the error contains all the information, you can do that depending on the error (like, no toasts for 404 errors). For additional information that you do not have on the error for some reason, use the meta field.

Is this pattern okay with you, or would you advise local onError handler for each query and mutation placed immediately after the server response in the local functions themselves?

I think that's totally fine. You can hoist up whatever logic you think would be repetitive on query levels to the global level.

d. In order to display toast for failed background queries, we are writing a global onError callback for "QueryCache". For the same reason, it needs to be written for MutationCache as well. Am I right?

Yes, if you want error toasts for mutations as well, they have the same global callbacks on the MutationCache.

[saeedPadyab]

@TkDodo could you please help me how to manage onError for both local and global in case I don't want to be executed global onError when I have local onError?

[TkDodo]

use the defaultOptions which will be overridden by specific queries.

[saeedPadyab]

@TkDodo Thanks for your reply. I have onError in defaultOptions for mutations globally shows toast error message but in some cases inside components, a useMutation has onError itself locally.
the issue is that useMutation's onError runs first then defaultOptions's onError executes.
I don't want defaultOption's onError to be executed if there is onError in the component locally.

[philippks]

@saeedPadyab I'm encountering exactly the same problem. Seems like the onError of the defaultOptions is only overwritten when defining the onError on useMutation, but not when defining onError on the actual mutate call. Maybe this helps you.

I think this is slightly unexpected. Do you know if this is on purpose @TkDodo ?

Edited: in the meantime I think it makes sense as it is, since one can define a "global onError" and add an additional "onError" on the function call. If one wants to overwrite it, it still can be defined when calling useMutation.

[TkDodo]

yes this is on purpose. callbacks are basically on useMutation. They fire always, and they can be defaulted with what we have in defaultOptions.

callbacks on .mutate are additional callbacks that works slightly differently:

1. if you fire mutate multiple times, only the last callback will be called. For useMutation, the callback will be called multiple times (once for each invocation).
2. if your component unmounts before the request finishes, callbacks on .mutate will not be called at all
3. You cannot return a Promise from callbacks on .mutate so that they can be awaited, but this works for useMutation callbacks.

I think all of this is documented here: https://tanstack.com/query/v4/docs/guides/mutations