Add meta to hydrated queries and mutations

[JanStevens]

Hi 👋 ,

To granularly hydrate queries (SSR and LocalStorage), we use the meta property on useQuery so we can specify if the query should be hydrated or not. By default we indicate that no query should be hydrated using the following setup:

const queryClient = new QueryClient({
  queryCache,
  defaultOptions: {
    queries: {
      refetchOnWindowFocus: false,
      retry: 2,
      meta: {
        // By default we don't want to hydrate queries
        hydrate: false,
      },
    },
  },
});

// Later on somewhere in SSR land
const dehydratedState = JSON.parse(
  JSON.stringify(
    dehydrate(queryClient, {
      shouldDehydrateQuery: ({ meta }) => !!meta?.dehydrate,
    }),
  ),
)

// Somewhere in prefetch SSR land
queryClient.prefetch({ 
  queryFn: () => ...,
  queryKey: ['key'],
  // Here comes the magic
  meta: { dehydrate: true },
})

This system works wonderfully but I notice that when we want to apply this to localStorage (which also uses the hydrate function internally). It all falls apart, assuming the following configuration

const queryClient = new QueryClient({
  queryCache,
  defaultOptions: {
    queries: {
      // Set cacheTime to 24h for persisted Cache
      cacheTime: 1000 * 60 * 60 * 24,
      refetchOnWindowFocus: false,
      retry: 2,
      meta: {
        // By default we don't want to store queries in local storage
        localStorage: false,
      },
    },
  },
});

const PersistOptions: PersistQueryClientProviderProps['persistOptions'] = {
  persister: LocalStoragePersistor,
  // Keep persisted cache for 12 hours
  maxAge: 1000 * 60 * 60 * 12,
  dehydrateOptions: {
    shouldDehydrateQuery: query => !!query.meta?.localStorage,
  },
};

What happens is the following:

1. Queries are executed, if they are marked with { meta: { localStorage: true } } they are stored in local storage 👍
2. We perform a refresh and the queries are restored, no network requests are made 👍 , but they are removed from localStorage 👎 . Because storing the queries does not contain the meta information shouldDehydrateQuery returns false causing the queries to be removed from localStorage
3. We perform another refresh and the queries perform a network request 👎

The solution seems trivial (but implications might not be) that hydrate should store / restore meta.

I've created a POC implementation with some tests on how to approach this https://github.com/TanStack/query/compare/main...JanStevens:query:feat/hydrate-query-meta?expand=1

WDYT?

[TkDodo]

while it looks like a good idea, the problem is that meta is an option, and not part of the state. We don't persist options, only state :) meta can also easily contain non-serializable things like functions.

What you can do though is provide defaultOptions to the hydration process:

const defaultOptions = {
  queries: {
      // Set cacheTime to 24h for persisted Cache
      cacheTime: 1000 * 60 * 60 * 24,
      refetchOnWindowFocus: false,
      retry: 2,
      meta: {
        // By default we don't want to store queries in local storage
        localStorage: false,
      },
  }
}

const queryClient = new QueryClient({
  queryCache,
  defaultOptions,
});

const PersistOptions: PersistQueryClientProviderProps['persistOptions'] = {
  persister: LocalStoragePersistor,
  // Keep persisted cache for 12 hours
  maxAge: 1000 * 60 * 60 * 12,
  dehydrateOptions: {
    shouldDehydrateQuery: query => !!query.meta?.localStorage,
  },
  hydrateOptions: {
    defaultOptions
  },
};

so that the same defaultOptions will be picked up during hydration.

[TkDodo]

what we could do is use the defaultOptions from the QueryClient if no default options were provided in hydrateOptions, basically, defaulting them to ones from the QueryClient inside the persist util:

query/packages/query-persist-client-core/src/persist.ts

Line 93 in 813962f

hydrate(queryClient, persistedClient.clientState, hydrateOptions)

This would be backwards compatible and sensible, so I'd accept a PR with the proper tests and documentation :)

[JanStevens]

It seems I totally overlooked the fact that you can indeed pass hydrateOptions to PersistOptions. This indeed solves the issues and it seems that you don't need any code changes. Not sure why I didn't saw this before 🤔.

Thanks for the reply, in my hydrateOptions I now return

export const PersistOptions: PersistQueryClientProviderProps['persistOptions'] =
  {
    persister: LocalStoragePersistor,
    // Keep persisted cache for 12 hours
    maxAge: 1000 * 60 * 60 * 12,
    dehydrateOptions: {
      dehydrateMutations: false,
      shouldDehydrateQuery: ({ meta }) => !!meta?.localStorage,
    },
    hydrateOptions: {
      defaultOptions: {
        queries: {
          meta: { localStorage: true },
        },
      },
    },
  };

So all hydrated queries have localStorage === true meaning next time they are retrieved they are not removed from the localStorage cache.