Proposal for queryClient.isPaused feature

[crutchcorn]

I'm working on an offline-first React Native app using TanStack Query. To do this, I'd like to have a banner at the top of the screen indicating when the user needs to sync with the server (using paused queries to do this)

This top banner should ideally hook into the "paused" fetchStatus of any queries that might be in the background.

const numberOfPaused = useIsPaused();

if (!numberOfPaused) return null;
return <p>You have {numberOfPaused} unsynced changed</p>;

While we could hand-roll a useIsPaused hook like so:

'use client'
import * as React from 'react'
import { notifyManager } from '@tanstack/query-core'

import { useQueryClient } from './QueryClientProvider'
import type { QueryClient, QueryFilters } from '@tanstack/query-core'

export function useIsPaused(
  filters?: QueryFilters,
  queryClient?: QueryClient,
): number {
  const client = useQueryClient(queryClient)
  const queryCache = client.getQueryCache()

  return React.useSyncExternalStore(
    React.useCallback(
      (onStoreChange) =>
        queryCache.subscribe(notifyManager.batchCalls(onStoreChange)),
      [queryCache],
    ),
    () => queryCache.findAll({...filters, fetchStatus: 'paused' }),
    () => queryCache.findAll({...filters, fetchStatus: 'paused' }),
  )
}

To handle this, a few thoughts:

1. This requires an awful lot of internals knowledge about TanStack Query to work as-expected
2. It would be nice to have this part of core so that we can encourage others to do more offline work using Query

I'm happy to introduce the relevant client.isPaused() and useIsPaused hooks if this idea is approved.

[TkDodo]

The hook won't exactly work because queryCache.findAll will yield a new array, and snapshots need to be referentially stable. That's why e.g. useMutationState uses a ref:

query/packages/react-query/src/useMutationState.ts

Lines 49 to 82 in 1d3ee67

	export function useMutationState<TResult = MutationState>(
	options: MutationStateOptions<TResult> = {},
	queryClient?: QueryClient,
	): Array<TResult> {
	const mutationCache = useQueryClient(queryClient).getMutationCache()
	const optionsRef = React.useRef(options)
	const result = React.useRef<Array<TResult>>()
	if (!result.current) {
	result.current = getResult(mutationCache, options)
	}
	React.useEffect(() => {
	optionsRef.current = options
	})
	return React.useSyncExternalStore(
	React.useCallback(
	(onStoreChange) =>
	mutationCache.subscribe(() => {
	const nextResult = replaceEqualDeep(
	result.current,
	getResult(mutationCache, optionsRef.current),
	)
	if (result.current !== nextResult) {
	result.current = nextResult
	notifyManager.schedule(onStoreChange)
	}
	}),
	[mutationCache],
	),
	() => result.current,
	() => result.current,
	)!
	}

useIsMutating uses this hook under the hood, so if we do this, I would say we come up with a useQueryState hook and derive useIsFetching and maybe usIsPaused from it, though useIsPaused could then be niche enough to be done in user-land with useQueryState.

---

on the other hand, you could also simply hook into the onlineManager and display an offline banner there? Not quite the same, because you can be offline and not have paused queries ...

---

so, I'm mostly concerned about api surface, but useQueryState with the same api as useMutationState sounds right to me. With filters and select, you can basically get anything you need. The mutation state hook also uses structuralSharing to make sure the select results won't change needlessly.

I'm even thinking that useIsFetching and useIsMutating could then be deprecated in favour of just:

useMutationState({ filters: { status: 'pending' }}.length

which isn't that much more and I don't think those hooks are widely used.

[crutchcorn]

I would say we come up with a useQueryState hook

I like this plan (along with deprecating useIsFetching and useIsMutating) a lot more than what I've outlined

On the other hand, you could also simply hook into the onlineManager and display an offline banner there?

Yeah, as you outlined the offline without paused queries are two different things in my mind. I also want to have an in-app "I am explicitly offline until I am explicitly online" flag for our needs (we have a lot of users with spotty internet so having a "No, I am really online flag would be immensely helpful for us) so we'd have both an offline flag and a "You have paused queries" type deal

I'm happy to take on this work to build out a useQueryState hook if this still sounds good to you

[TkDodo]

I'm happy to take on this work to build out a useQueryState hook if this still sounds good to you

yeah, let's do this. There might some things you can use from the useMutationState hook, and maybe we can even unify some of the internals with shared code. They should be pretty much the same except that one subscribes to queryCache, the other to mutationCache, and they have differently typed filters :)