Compatibility between Mutation and useMutation, queryClient.fetchQuery and useQuery.

[zacharyweidenbach]

Preface

I am in the process of writing a React interface framework called Chimeric. It is special kind of interface generator that creates both idiomatic and reactive methods that can be called outside of react (idiomatic path), or within react as a hook (reactive path). These two methods are fused together into a singular type in order to colocate the functionality that is abstracted behind the interface, and to reduce the mental burden of having to reason about your code in reactive and non-reactive terms when you need to eject from react to orchestrate more complicated logic idiomatically. The end result is code that looks like this:

// idiomatic
const todos = getTodos();

// reactively within a React component/hook
const todos = getTodos.use();

The name I came up with to describe this duality is a "chimeric" interface, hence the name of the project.

The library itself has a core that is not coupled to tanstack query. However, it does express the idea of a "mutation" and a "query" in a way that is generalized. The idea there is that chimeric's definition of a mutation or a query can be reimplemented using tanstack query or some other library, like RTK query (I haven't gotten there yet).

Reason for the discussion

I am hoping to get some feedback from people with the deepest knowledge of the inner workings of tanstack query to see if I have implemented the compatibility between useMutation and Mutation as well as queryClient.fetchQuery and useQuery correctly.

Mutations

Here is what a chimeric definition of a mutation looks like for reference.
And how it gets used.

Idiomatic Path

To create idiomatic compatibility with useMutation, I am using the Mutation api to achieve this. However, I did notice that the Mutation api needs a mutationId if it is to correctly associate the mutation with the state of a useMutation instance that uses a mutationKey. I set the mutationId default to 0 if it cannot find an existing mutationId with the provided mutationKey (if a mutationKey is provided). Is this a sane default if a mutationId cannot be found?

Reactive Path

The mutationOptions supported by Tanstack query are passed through to useMutation. Chimeric redefines the types that are allowed to be passed through as those which live in Tanstack query's MutationOptions type.

Queries

Here is what a chimeric definition of a query looks like for reference.
And how it gets used reactively and idiomatically.

Idiomatic Path

To create idiomatic compatibility with useQuery, I am using the QueryClient.fetchQuery interface. This allows me to access the same cache as useQuery such that idiomatic calls will return the cached value instead of refetching.

However, sometimes it is useful to be able to imperatively force a query to refetch its data. I only allow this on the idiomatic member because the reactive member provides a refetch function to do the same thing. The call signature for doing this in chimeric would look something like:

const refetchedData = someChimericQuery({ options: { forceRefetch: true } });

To achieve this with queryClient.fetchQuery, I am invalidating the query prior to calling the fetchQuery.

https://github.com/dataquail/chimeric/blob/main/packages/react-query/src/lib/Query/IdiomaticQueryFactory.ts#L44

Is this the recommended way to achieve such functionality? I did not see anything in the documentation to indicate there was an argument to achieve this directly with fetchQuery. It works but feels hacky.

Reactive Path

For now, the only override option supported by reactive queries is the enabled flag. I may add more if it makes sense, but I don't want to let implementation details leak into the chimeric core types if I can avoid it. At the time of definition, the ChimericQueryFactory expects to be handed a function that returns a QueryOptions type defined by Tanstack Query. This side steps the need to redefine the supported passthru types like with chimeric mutations.

Conclusion

So far I have been able to achieve compatibility with idiomatic and reactive versions of mutations and queries, but any feedback for pitfalls or gotchas are welcome.

Thanks for this awesome tool and community.

[TkDodo]

To create idiomatic compatibility with useMutation, I am using the Mutation api to achieve this.

you’d want queryClient.getMutationCache().build(...):

query/packages/query-core/src/mutationCache.ts

Lines 96 to 111 in 19b95c4

	build<TData, TError, TVariables, TContext>(
	client: QueryClient,
	options: MutationOptions<TData, TError, TVariables, TContext>,
	state?: MutationState<TData, TError, TVariables, TContext>,
	): Mutation<TData, TError, TVariables, TContext> {
	const mutation = new Mutation({
	mutationCache: this,
	mutationId: ++this.#mutationId,
	options: client.defaultMutationOptions(options),
	state,
	})
	this.add(mutation)
	return mutation
	}

That will give you a Mutation, and then you can call .execute() on it. This is what mutate in our QueryObserver does:

query/packages/query-core/src/mutationObserver.ts

Line 111 in 75131d6

mutate(

To achieve this with queryClient.fetchQuery, I am invalidating the query prior to calling the fetchQuery.

invalidation refetches queries if they are active. calling fetchQuery with staleTime: 0 also guarantees that data will be fetched, as it’s always stale. I would just do that:

const staleTime = options?.forceRefetch ? 0 : options.staleTime

return queryClient.fetchQuery({
  ...queryOptions,
  staleTime,
  queryKey: queryOptions.queryKey,
  queryFn: queryOptions.queryFn,
});

without the invalidation part

expects to be handed a function that returns a QueryOptions type defined by Tanstack Query

that’s perfect.

[zacharyweidenbach]

Thank you for taking the time to read and respond!

The change for sourcing the mutation makes total sense, thank you for the insight.

Followup question to the staleTime suggestion.

Suppose a caller wants to imperatively force a refetch but maintain the staleTime that was defined at the definition. If I leverage staleTime to force a refetch, wouldn't that also override the staleTime that was set when the useQuery hook is first defined?

[TkDodo]

Suppose a caller wants to imperatively force a refetch but maintain the staleTime that was defined at the definition. If I leverage staleTime to force a refetch, wouldn't that also override the staleTime that was set when the useQuery hook is first defined?

staleTime cannot be “set” on a query, because a query doesn’t have staleTime. It’s an “observer” level concept, so it depends on how you “look at it”. For useQuery, they just each have their own staleTime stored on the observer, so they can always compare “how old is the query data compared to how accurate I want to have it”? This can be different per screen.

For imperative methods like fetchQuery, we just use staleTime to do a one-of comparison to know if we have to trigger the fetch, see:

query/packages/query-core/src/queryClient.ts

Lines 366 to 370 in 8f8e6d0

	return query.isStaleByTime(
	resolveStaleTime(defaultedOptions.staleTime, query),
	)
	? query.fetch(defaultedOptions)
	: Promise.resolve(query.state.data as TData)

[zacharyweidenbach]

Okay that clarifies my mental model. So a fetchQuery passing a staleTime will not affect the staleTime already associated with any running useQuery with the same queryKey, if I understand what you are saying. Thanks again.