Implement Delayed Query Invalidation Until All LocalStorage Mutations are Processed in React Query

[tahamansoor]

Hello @TkDodo,
I am currently utilizing React Query to manage the state and synchronization of data in an application with offline capabilities. Our setup involves saving mutations to local storage when the client is offline. Upon regaining internet connectivity, these mutations are processed sequentially.
Issue: Each mutation triggers query invalidations immediately upon processing. This behavior is suboptimal because it can lead to unnecessary re-fetching and potential performance issues, especially when multiple mutations are involved.
Requirement: I am seeking a more efficient approach where no queries are invalidated while mutations are still being processed. Only after all mutations stored in localStorage are completed should the queries be invalidated collectively. This would ensure that the data remains consistent and minimizes the number of re-fetches.
Proposed Solution: Ideally, I would like to implement a mechanism where query invalidation is queued and executed only after all offline mutations have been successfully applied. This approach would likely involve modifications to the mutation synchronization logic to batch or defer the invalidation process until after all mutations are settled.
Could you please provide guidance or consider enhancing the library to support this use case? It would greatly benefit applications that heavily rely on offline functionality and need to manage data synchronization efficiently when coming back online.

Here's my approach:

import { createSyncStoragePersister } from "@tanstack/query-sync-storage-persister"
import {
  MutationCache,
  QueryClient,
  onlineManager,
} from "@tanstack/react-query"
import { ReactQueryDevtools } from "@tanstack/react-query-devtools"
import { PersistQueryClientProvider } from "@tanstack/react-query-persist-client"
import React from "react"
import { _QK } from "../helpers/queryKeys"

const BUILD_ID = (process.env as any).CONFIG_BUILD_ID
console.log("Current BUILD_ID:", BUILD_ID)

// Create QueryClient
const queryClient: QueryClient = new QueryClient({
  defaultOptions: {
    queries: {
      cacheTime: Infinity,
      refetchOnWindowFocus: false,
      networkMode: "offlineFirst",
      refetchOnReconnect: (query) => {
        return !!queryClient
          .getMutationCache()
          .getAll()
          .filter((mutation) => mutation.state.isPaused).length
      },
    },
  },
  mutationCache: new MutationCache({
    onMutate: async (variables, mutation) => {
      if (mutation?.meta?.invalidates) {
        await Promise.all(
          mutation.meta?.invalidates.map((key) => {
            return queryClient.cancelQueries({
              queryKey: _QK[key](mutation.state.variables as any),
            })
          })
        )
      }
    },
    onSuccess: async (data, variables, context, mutation) => {
      if (mutation?.meta?.invalidates) {
        await Promise.all(
          mutation.meta?.invalidates.map((key) => {
            return queryClient.invalidateQueries({
              queryKey: _QK[key](mutation.state.variables as any),
            })
          })
        )
      }
    },
    onError: (error, variables, context, mutation) => {},
  }),
})

const QueryWrapper: React.FC<React.PropsWithChildren> = ({ children }) => {
  const [isMounted, setIsMounted] = React.useState(false)
  React.useEffect(() => {
    setIsMounted(true)

    const setOnline = () => {
      void onlineManager.setOnline(navigator.onLine)
    }

    window.addEventListener("online", setOnline)
    window.addEventListener("offline", setOnline)

    return () => {
      window.removeEventListener("online", setOnline)
      window.removeEventListener("offline", setOnline)
    }
  }, [])

  if (!isMounted) return null

  return (
    <PersistQueryClientProvider
      client={queryClient}
      persistOptions={{
        persister: createSyncStoragePersister({
          storage: window.localStorage,
        }),
      }}
      onSuccess={() => {
        queryClient.resumePausedMutations().then(() => {
          queryClient.invalidateQueries()
        })
      }}
    >
      {children}
      <ReactQueryDevtools initialIsOpen={false} />
    </PersistQueryClientProvider>
  )
}

export default QueryWrapper

[TkDodo]

Ideally, I would like to implement a mechanism where query invalidation is queued and executed only after all offline mutations have been successfully applied. This approach would likely involve modifications to the mutation synchronization logic to batch or defer the invalidation process until after all mutations are settled.

Invalidation is something that you do on your own - it's not the library doing it. Long story short, if you don't want invalidations at a certain point (e.g. while you are still resuming paused mutations), then don't call queryClient.invalidateQueries.

Usually, invalidation happens in onSuccess / onSettled callbacks of useMutation, and when the mutations resume after coming online, the mutations that resume do not have those callbacks attached anymore. So I'd say that per default, you won't have that problem. If you set up global invalidation in the cache level callback (like shown in your example), you need to make sure it doesn't invalidate yourself.