useQuery meta data

[zaguiini]

For a lot of use cases, it's very useful to have some way of passing metadata to the query options, so it can be accessed in some places. My main use case, and one I cannot work around right now without some hacking with the query key, is the following:

I'm persisting the data using the persistQueryClient. That's working great, however there are some queries I do not want to persist (like search results, for example). The only way I found right now would be to create a property on the query key and then checking if this property exists inside shouldDehydrateQuery. If it does, ignore that query and don't persist it.

That's the code I have right now: https://codesandbox.io/s/pedantic-agnesi-71dmf

The idea and proposed API, would be to include a property called meta or context (like apollo-client has), which can be accessed elsewhere as needed. Example:

const MyComponent = () => {
  useQuery(['users', 123], () => fetch(), {
    meta: {
      persist: false
    }
  })

  return null
}

And then, for example, you can look for the meta property on shouldDehydrateQuery:

persistQueryClient({
  queryClient,
  persistor: localStoragePersistor,
  dehydrateOptions: {
    shouldDehydrateQuery: (query) => query.meta.persist ?? true
  }
})

That's somewhat related to #2286. This is a very common pattern on the apollo-client world as seen here and explained in detail on this article.

I'm willing to implement that if I get the green light. I think it's super useful in a variety of cases and should definitely be implemented.

[TkDodo]

hmm, is it so wrong to use the queryKey for that? I mean, maybe not by attaching a .persist flag onto the array, but maybe by structuring the query keys into private and public queries?

['private', 'users', 123]
['public', 'todos', 456]

but yeah, I can also get behind the idea of a meta field in the query options. It would likely be available wherever the query is available, and it should likely also be attached to the QueryContext so that it's passed to the queryFn.

One problem might be getting the typings right. We'd probably want to allow anything on the context, or at least any object, so it would be typed as Record<PropertyKey, unknown> for most cases. However, for the QueryFunctionContext, it would be nice to get type inference, like:

  useQuery(['users', 123], (context) => fetchIt(context.meta), {
    meta: {
      persist: false
    } as const
  })

here, context.meta should be of type readonly { persist: false }. This was quite the complex task to get done for the QueryKey and involved adding another generic almost everywhere, which I would like to avoid again if possible ...

[zaguiini]

by structuring the query keys into private and public queries

I would prefer not to include that kind of information on my cache, it has nothing to do with my back-end structure, nor with the query itself -- it's only related to persistence. I think it's a totally separated concern which should not be mixed with different things.

I believe we should indeed type meta (let's call it that way, it's shorter) as Record<PropertyKey, unknown> and not worry about it too much. I think it'd be cumbersome to export a singleton just for that matter. apollo-client does it like that and it's not problematic. It would definitely be nice, but it would be hard to implement and for the users to get it right since they'd need to re-export the types and query client, so additional steps (that might be opt-in though).

[tannerlinsley]

I think this would be a good addition @TkDodo. I have wanted something like this myself lately.

[tannerlinsley]

@zaguiini Would you feel comfortable heading up a PR to add this functionality?

[zaguiini]

Yeah! I'll try and find free slots.

[zaguiini]

@tannerlinsley,

I've been taking a look at the code before taking any action, and it looks like simply adding

meta?: Record<string, unknown>

To the QueryOptions interface would be enough to achieve the desired functionality.

However, the path to the meta object would be:

query.options.meta

I'd like to drop the options and leave it as just query.meta, but that comes at a price:

1. Another property in the query class;
2. A bit more complex setOptions method (since meta will come from the options object);
3. A more complex QueryOptions which would exclude meta from everywhere but the constructor of the Query class.

It looks like the trade-off is not worth it, but that's not my library and I'd like your opinion first. 😄

Also, I saw we have an option called behavior. For the specific case of not persisting a query, we could add a property on behavior called persist which defaults to true. We could, then, use that property before calling the shouldDehydrateQuery callback so there's no customization needed by the user.

I don't think it would be a replacement for meta, but they could live together and it would surely make the API more idiomatic since not persisting a query is actually a behavior, so naming fits the purpose in this case.

What do you think about it?

Thanks!

[TkDodo]

I think we should treat it similar to the queryKey, which is available on the Query itself as well as in the options.

[TkDodo]

also:

and it should likely also be attached to the QueryContext so that it's passed to the queryFn.

also a good idea I think, and since the context is an object, also non-breaking

[zaguiini]

@TkDodo sorry, I just updated my comment. Can you take a look at the sentence before What do you think about it?

[TkDodo]

The behavior is used internally to distinguish an infinteQuery from a normal query. I don't think you can / should set anything on there as a consumer. It's undocmented, and probably we should also remove it from the options that are exposed to consumers

[zaguiini]

I see. Maybe right now it would be an option to re-evaluate its role? It looks like a perfect fit, not gonna lie :) No hard feelings if it doesn't work but it'd look 👌

[zaguiini]

PR ready on #2818.

[DaleWebb]

Thanks for the addition of the meta field in the query options.

I wanted to strongly type the field in a project I'm working on. Currently, as QueryMeta and MutationMeta are types, it isn't possible to change the shape. To address this, I changed those types to interfaces so that I could override the shape with the following mechanism:

interface Meta {
  persist?: boolean;
}

declare module '@tanstack/react-query' {
  interface QueryMeta extends Meta {}
}

I added a PR that would allow this type of override here: #4253

[tomerzcod7]

Sorry to open an old issue.
I've been trying to use the meta field to check if a query should be persisted as well, but it seems like the meta object itself is not persisted with the query.

Any way around this?

[TkDodo]

but it seems like the meta object itself is not persisted with the query.

we've added this in v5

[enchorb]

Using v5 but not seeing the meta property on useInfiniteQuery. For context, am using this on the predicate function of queryClient.removeQueries to remove all queries with meta.type === 'private' on user sign out. However for infinite queries the meta object is undefined

[TkDodo]

show a reproduction please, because as far as I can see, meta is there for useInfiniteQuery as well.

[JunyeongChoi0]

For those still wondering how to type meta by declare module:

docs

My working .d.ts file

interface Meta {
  queryMeta: { foobar?: boolean }
}

declare module '@tanstack/react-query' {
  interface Register extends Meta {}
}

Working screenshot in VSCode

[joeyfigaro]

For those of us currently stuck on v4, what's the best way to gain typed meta on both queries and mutations?

[TkDodo]

sorry, it doesn't exist in v4, so there is no good way except updating to v5. what troubles are you having with upgrading?

[joeyfigaro]

@TkDodo apologies for the delay here–we're currently stuck on React 17. It looks like v5 requires v18, unfortunately. :|

[iambryanhaney]

Mostly an academic question / I'm not advocating any pattern:

Since meta can contain anything, that includes closures, derived state, etc. In the case of the deprecated query callbacks, the behavior was defined -- using a query in multiple components would fire each callback in its own instance.

Being that the global QueryCache callbacks only fire once, what is the behavior if a query is used in multiple components with different metas per instance? I'm assuming that the last-invoked query's meta wins, or something along those lines?

[TkDodo]

I'm assuming that the last-invoked query's meta wins, or something along those lines?

yes, that. but don’t rely on this behaviour please. meta is, just like queryFn, meant to be set equally by all instances