feat(persistQueryClient): PersistQueryClientProvider

docs/src/pages/plugins/persistQueryClient.md

@@ -48,6 +48,58 @@ It should be set as the same value or higher than persistQueryClient's `maxAge`
 
 You can also pass it `Infinity` to disable garbage collection behavior entirely.
 
+## Usage with React
+
+[persistQueryClient](#persistQueryClient) will try to restore the cache and automatically subscribes you to further changes, thus syncing your client to the provided storage.
+
+However, restoring is asynchronous, because all persisters are async by nature, which means that if you render your App while you are restoring, you might get into race conditions if a query mounts and fetches at the same time.
+
+Further, if you subscribe to changes outside of react lifecycles, you have no way of unsubscribing:
+
+```js
+// 🚨 never unsubscribes from syncing
+persistQueryClient({
+  queryClient,
+  persister: localStoragePersister,
+})
+
+// 🚨 happens at the same time as restoring
+ReactDOM.render(<App />, rootElement)
+```
+
+### PeristQueryClientProvider
+
+For this use-case, you can use the `PersistQueryClientProvider`. It will make sure to subscribe / unsubscribe correctly according to the React lifecycle, and it will also make sure that queries will not start fetching while we are still restoring. Queries will still render though, they will just be put into `fetchingState: 'idle'` until data has been restored. Then, they will refetch unless the restored data is _fresh_ enough, and _initialData_ will also be respected. It can be used _instead of_ the normal `QueryClientProvider`:
+
+```jsx
+
+import { PersistQueryClientProvider } from 'react-query/persistQueryClient'
+import { createWebStoragePersister } from 'react-query/createWebStoragePersister'
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      cacheTime: 1000 * 60 * 60 * 24, // 24 hours
+    },
+  },
+})
+
+const persister = createWebStoragePersister({
+  storage: window.localStorage,
+})
+
+ReactDOM.render(
+  <PersistQueryClientProvider
+    client={queryClient}
+    persistOptions={{ persister }}
+  >
+    <App />
+  </PersistQueryClientProvider>,
+  rootElement
+)
+
+```
+
 ## How does it work?
 
 - A check for window `undefined` is performed prior to saving/restoring/removing your data (avoids build errors).

src/core/queryObserver.ts

@@ -418,7 +418,7 @@ export class QueryObserver<
     let data: TData | undefined
 
     // Optimistically set result in fetching state if needed
-    if (options.optimisticResults) {
+    if (options._optimisticResults) {
       const mounted = this.hasListeners()
 
       const fetchOnMount = !mounted && shouldFetchOnMount(query, options)
@@ -434,6 +434,9 @@ export class QueryObserver<
           status = 'loading'
         }
       }
+      if (options._optimisticResults === 'isHydrating') {
+        fetchStatus = 'idle'
+      }
     }
 
     // Keep previous data if needed

src/core/types.ts

@@ -206,12 +206,8 @@ export interface QueryObserverOptions<
    * If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `loading` data and no initialData has been provided.
    */
   placeholderData?: TQueryData | PlaceholderDataFunction<TQueryData>
-  /**
-   * If set, the observer will optimistically set the result in fetching state before the query has actually started fetching.
-   * This is to make sure the results are not lagging behind.
-   * Defaults to `true`.
-   */
-  optimisticResults?: boolean
+
+  _optimisticResults?: 'optimistic' | 'isHydrating'
 }
 
 type WithRequired<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>

src/persistQueryClient/PersistQueryClientProvider.tsx

@@ -0,0 +1,46 @@
+import React from 'react'
+
+import { persistQueryClient, PersistQueryClientOptions } from './persist'
+import { QueryClientProvider, QueryClientProviderProps } from '../reactjs'
+import { IsHydratingProvider } from '../reactjs/Hydrate'
+
+export interface PersistQueryClientProviderProps
+  extends QueryClientProviderProps {
+  persistOptions: Omit<PersistQueryClientOptions, 'queryClient'>
+  onSuccess?: () => void
+}
+
+export const PersistQueryClientProvider = ({
+  client,
+  children,
+  persistOptions,
+  onSuccess,
+  ...props
+}: PersistQueryClientProviderProps): JSX.Element => {
+  const [isHydrating, setIsHydrating] = React.useState(true)
+  const refs = React.useRef({ persistOptions, onSuccess })
+
+  React.useEffect(() => {
+    refs.current = { persistOptions, onSuccess }
+  })
+
+  React.useEffect(() => {
+    const [unsubscribe, promise] = persistQueryClient({
+      ...refs.current.persistOptions,
+      queryClient: client,
+    })
+
+    promise.then(() => {
+      refs.current.onSuccess?.()
+      setIsHydrating(false)
+    })
+
+    return unsubscribe
+  }, [client])
+
+  return (
+    <QueryClientProvider client={client} {...props}>
+      <IsHydratingProvider value={isHydrating}>{children}</IsHydratingProvider>
+    </QueryClientProvider>
+  )
+}

src/persistQueryClient/index.ts

@@ -1,142 +1,2 @@
-import { QueryClient } from '../core'
-import { getLogger } from '../core/logger'
-import {
-  dehydrate,
-  DehydratedState,
-  DehydrateOptions,
-  HydrateOptions,
-  hydrate,
-} from 'react-query'
-import { Promisable } from 'type-fest'
-
-export interface Persister {
-  persistClient(persistClient: PersistedClient): Promisable<void>
-  restoreClient(): Promisable<PersistedClient | undefined>
-  removeClient(): Promisable<void>
-}
-
-export interface PersistedClient {
-  timestamp: number
-  buster: string
-  clientState: DehydratedState
-}
-
-export interface PersistQueryClienRootOptions {
-  /** The QueryClient to persist */
-  queryClient: QueryClient
-  /** The Persister interface for storing and restoring the cache
-   * to/from a persisted location */
-  persister: Persister
-  /** A unique string that can be used to forcefully
-   * invalidate existing caches if they do not share the same buster string */
-  buster?: string
-}
-
-export interface PersistedQueryClientRestoreOptions
-  extends PersistQueryClienRootOptions {
-  /** The max-allowed age of the cache in milliseconds.
-   * If a persisted cache is found that is older than this
-   * time, it will be discarded */
-  maxAge?: number
-  /** The options passed to the hydrate function */
-  hydrateOptions?: HydrateOptions
-}
-
-export interface PersistedQueryClientSaveOptions
-  extends PersistQueryClienRootOptions {
-  /** The options passed to the dehydrate function */
-  dehydrateOptions?: DehydrateOptions
-}
-
-export interface PersistQueryClientOptions
-  extends PersistedQueryClientRestoreOptions,
-    PersistedQueryClientSaveOptions,
-    PersistQueryClienRootOptions {}
-
-/**
- * Restores persisted data to the QueryCache
- *  - data obtained from persister.restoreClient
- *  - data is hydrated using hydrateOptions
- * If data is expired, busted, empty, or throws, it runs persister.removeClient
- */
-export async function persistQueryClientRestore({
-  queryClient,
-  persister,
-  maxAge = 1000 * 60 * 60 * 24,
-  buster = '',
-  hydrateOptions,
-}: PersistedQueryClientRestoreOptions) {
-  if (typeof window !== 'undefined') {
-    try {
-      const persistedClient = await persister.restoreClient()
-
-      if (persistedClient) {
-        if (persistedClient.timestamp) {
-          const expired = Date.now() - persistedClient.timestamp > maxAge
-          const busted = persistedClient.buster !== buster
-          if (expired || busted) {
-            persister.removeClient()
-          } else {
-            hydrate(queryClient, persistedClient.clientState, hydrateOptions)
-          }
-        } else {
-          persister.removeClient()
-        }
-      }
-    } catch (err) {
-      getLogger().error(err)
-      getLogger().warn(
-        'Encountered an error attempting to restore client cache from persisted location. As a precaution, the persisted cache will be discarded.'
-      )
-      persister.removeClient()
-    }
-  }
-}
-
-/**
- * Persists data from the QueryCache
- *  - data dehydrated using dehydrateOptions
- *  - data is persisted using persister.persistClient
- */
-export async function persistQueryClientSave({
-  queryClient,
-  persister,
-  buster = '',
-  dehydrateOptions,
-}: PersistedQueryClientSaveOptions) {
-  if (typeof window !== 'undefined') {
-    const persistClient: PersistedClient = {
-      buster,
-      timestamp: Date.now(),
-      clientState: dehydrate(queryClient, dehydrateOptions),
-    }
-
-    await persister.persistClient(persistClient)
-  }
-}
-
-/**
- * Subscribe to QueryCache updates (for persisting)
- * @returns an unsubscribe function (to discontinue monitoring)
- */
-export function persistQueryClientSubscribe(
-  props: PersistedQueryClientSaveOptions
-) {
-  return props.queryClient.getQueryCache().subscribe(() => {
-    persistQueryClientSave(props)
-  })
-}
-
-/**
- * Restores persisted data to QueryCache and persists further changes.
- * (Retained for backwards compatibility)
- */
-export async function persistQueryClient(props: PersistQueryClientOptions) {
-  if (typeof window !== 'undefined') {
-    // Attempt restore
-    await persistQueryClientRestore(props)
-
-    // Subscribe to changes in the query cache to trigger the save
-    return persistQueryClientSubscribe(props)
-  }
-}
+export * from './persist'
+export * from './PersistQueryClientProvider'