chore: some docs

Author: DamianOsipiuk

docs/framework/react/plugins/createPersister.md

@@ -35,7 +35,7 @@ bun add @tanstack/query-persist-client-core
 
 - Import the `experimental_createQueryPersister` function
 - Create a new `experimental_createQueryPersister`
-  - you can pass any `storage` to it that adheres to the `AsyncStorage` or `Storage` interface - the example below uses the async-storage from React Native.
+  - you can pass any `storage` to it that adheres to the `AsyncStorage` interface - the example below uses the async-storage from React Native.
 - Pass that `persister` as an option to your Query. This can be done either by passing it to the `defaultOptions` of the `QueryClient` or to any `useQuery` hook instance.
   - If you pass this `persister` as `defaultOptions`, all queries will be persisted to the provided `storage`. You can additionally narrow this down by passing `filters`. In contrast to the `persistClient` plugin, this will not persist the whole query client as a single item, but each query separately. As a key, the query hash is used.
   - If you provide this `persister` to a single `useQuery` hook, only this Query will be persisted.
@@ -69,6 +69,56 @@ const queryClient = new QueryClient({
 
 The `createPersister` plugin technically wraps the `queryFn`, so it doesn't restore if the `queryFn` doesn't run. In that way, it acts as a caching layer between the Query and the network. Thus, the `networkMode` defaults to `'offlineFirst'` when a persister is used, so that restoring from the persistent storage can also happen even if there is no network connection.
 
+## Additional utilities
+
+Invoking `experimental_createQueryPersister` returns additional utilities in addition to `persisterFn` for easier implementation of userland functionalities.
+
+### `persistQueryByKey(queryKey: QueryKey, queryClient: QueryClient): Promise<void>`
+
+This function will persist `Query` to storage and key defined when creating persister.  
+This utility might be used along `setQueryData` to persist optimistic update to storage without waiting for invalidation.
+
+```tsx
+const persister = experimental_createQueryPersister({
+  storage: AsyncStorage,
+  maxAge: 1000 * 60 * 60 * 12, // 12 hours
+})
+
+const queryClient = useQueryClient()
+
+useMutation({
+  mutationFn: updateTodo,
+  onMutate: async (newTodo) => {
+    ...
+    // Optimistically update to the new value
+    queryClient.setQueryData(['todos'], (old) => [...old, newTodo])
+    // And persist it to storage
+    persister.persistQueryByKey(['todos'], queryClient)
+    ...
+  },
+})
+```
+
+### `retrieveQuery<T>(queryHash: string): Promise<T | undefined>`
+
+This function would attempt to retrieve persisted query by `queryHash`.  
+If `query` is `expired`, `busted` or `malformed` it would be removed from the storage instead, and `undefined` would be returned.
+
+### `persisterGc(): Promise<void>`
+
+This function can be used to sporadically clean up stoage from `expired`, `busted` or `malformed` entries.
+
+For this function to work, your storage must expose `entries` method that would return a `key-value tuple array`.  
+For example `Object.entries(localStorage)` for `localStorage` or `entries` from `idb-keyval`.
+
+### `persisterRestoreAll(queryClient: QueryClient): Promise<void>`
+
+This function can be used to restore all queries that are currently stored by persister in one go.  
+For example when your app is starting up in offline mode, or you want data from previous session to be immediately available without intermediate `loading` state.
+
+For this function to work, your storage must expose `entries` method that would return a `key-value tuple array`.  
+For example `Object.entries(localStorage)` for `localStorage` or `entries` from `idb-keyval`.
+
 ## API
 
 ### `experimental_createQueryPersister`
@@ -118,10 +168,11 @@ export interface StoragePersisterOptions {
   filters?: QueryFilters
 }
 
-interface AsyncStorage {
-  getItem: (key: string) => Promise<string | undefined | null>
-  setItem: (key: string, value: string) => Promise<unknown>
-  removeItem: (key: string) => Promise<void>
+interface AsyncStorage<TStorageValue = string> {
+  getItem: (key: string) => MaybePromise<TStorageValue | undefined | null>
+  setItem: (key: string, value: TStorageValue) => MaybePromise<unknown>
+  removeItem: (key: string) => MaybePromise<void>
+  entries?: () => MaybePromise<Array<[key: string, value: TStorageValue]>>
 }
 ```
 

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

@@ -145,6 +145,22 @@ export function experimental_createQueryPersister<TStorageValue = string>({
     return
   }
 
+  async function persistQueryByKey(queryKey: QueryKey, queryClient: QueryClient) {
+    if (storage != null) {
+      const query = queryClient.getQueryCache().find({ queryKey })
+      if (query) {
+        persistQuery(query)
+      } else {
+        if (process.env.NODE_ENV === 'development') {
+          console.warn(
+            'Could not find query to be persisted. QueryKey:',
+            JSON.stringify(queryKey)
+          )
+        }
+      }
+    }
+  }
+
   async function persistQuery(query: Query) {
     if (storage != null) {
       const storageKey = `${prefix}-${query.queryHash}`
@@ -251,6 +267,7 @@ export function experimental_createQueryPersister<TStorageValue = string>({
   return {
     persisterFn,
     persistQuery,
+    persistQueryByKey,
     retrieveQuery,
     persisterGc,
     persisterRestoreAll,