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.