fix(experimental_createQueryPersister): return more utilities, rename persister

Author: DamianOsipiuk

docs/framework/react/plugins/createPersister.md

@@ -1,6 +1,6 @@
 ---
 id: createPersister
-title: experimental_createPersister
+title: experimental_createQueryPersister
 ---
 
 ## Installation
@@ -33,8 +33,8 @@ bun add @tanstack/query-persist-client-core
 
 ## Usage
 
-- Import the `experimental_createPersister` function
-- Create a new `experimental_createPersister`
+- 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.
 - 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.
@@ -47,16 +47,18 @@ Garbage collecting a Query from memory **does not** affect the persisted data. T
 ```tsx
 import AsyncStorage from '@react-native-async-storage/async-storage'
 import { QueryClient } from '@tanstack/react-query'
-import { experimental_createPersister } from '@tanstack/query-persist-client-core'
+import { experimental_createQueryPersister } from '@tanstack/query-persist-client-core'
+
+const persister = experimental_createQueryPersister({
+  storage: AsyncStorage,
+  maxAge: 1000 * 60 * 60 * 12, // 12 hours
+})
 
 const queryClient = new QueryClient({
   defaultOptions: {
     queries: {
       gcTime: 1000 * 30, // 30 seconds
-      persister: experimental_createPersister({
-        storage: AsyncStorage,
-        maxAge: 1000 * 60 * 60 * 12, // 12 hours
-      }),
+      persister: persister.persisterFn,
     },
   },
 })
@@ -68,10 +70,10 @@ The `createPersister` plugin technically wraps the `queryFn`, so it doesn't rest
 
 ## API
 
-### `experimental_createPersister`
+### `experimental_createQueryPersister`
 
 ```tsx
-experimental_createPersister(options: StoragePersisterOptions)
+experimental_createQueryPersister(options: StoragePersisterOptions)
 ```
 
 #### `Options`

docs/framework/vue/plugins/createPersister.md

@@ -1,6 +1,6 @@
 ---
 id: createPersister
-title: experimental_createPersister
+title: experimental_createQueryPersister
 ---
 
 ## Installation
@@ -31,8 +31,8 @@ bun add @tanstack/query-persist-client-core
 
 ## Usage
 
-- Import the `experimental_createPersister` function
-- Create a new `experimental_createPersister`
+- 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
 - 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.
@@ -44,16 +44,18 @@ Garbage collecting a Query from memory **does not** affect the persisted data. T
 
 ```tsx
 import { QueryClient } from '@tanstack/vue-query'
-import { experimental_createPersister } from '@tanstack/query-persist-client-core'
+import { experimental_createQueryPersister } from '@tanstack/query-persist-client-core'
+
+const persister = experimental_createQueryPersister({
+  storage: AsyncStorage,
+  maxAge: 1000 * 60 * 60 * 12, // 12 hours
+})
 
 const queryClient = new QueryClient({
   defaultOptions: {
     queries: {
       gcTime: 1000 * 30, // 30 seconds
-      persister: experimental_createPersister({
-        storage: localStorage,
-        maxAge: 1000 * 60 * 60 * 12, // 12 hours
-      }),
+      persister: persister.persisterFn,
     },
   },
 })
@@ -65,10 +67,10 @@ The `createPersister` plugin technically wraps the `queryFn`, so it doesn't rest
 
 ## API
 
-### `experimental_createPersister`
+### `experimental_createQueryPersister`
 
 ```tsx
-experimental_createPersister(options: StoragePersisterOptions)
+experimental_createQueryPersister(options: StoragePersisterOptions)
 ```
 
 #### `Options`

examples/vue/persister/src/Post.vue

@@ -4,7 +4,7 @@ import { defineComponent } from 'vue'
 import { useQuery } from '@tanstack/vue-query'
 
 import { Post } from './types'
-import { experimental_createPersister } from '@tanstack/query-persist-client-core'
+import { experimental_createQueryPersister } from '@tanstack/query-persist-client-core'
 
 const fetcher = async (id: number): Promise<Post> =>
   await fetch(`https://jsonplaceholder.typicode.com/posts/${id}`).then(
@@ -24,13 +24,13 @@ export default defineComponent({
     const { isPending, isError, isFetching, data, error } = useQuery({
       queryKey: ['post', props.postId] as const,
       queryFn: () => fetcher(props.postId),
-      persister: experimental_createPersister({
+      persister: experimental_createQueryPersister({
         storage: {
           getItem: (key: string) => get(key),
           setItem: (key: string, value: string) => set(key, value),
           removeItem: (key: string) => del(key),
         },
-      }),
+      }).persisterFn,
     })
 
     return { isPending, isError, isFetching, data, error }

examples/vue/persister/src/Posts.vue

@@ -1,7 +1,7 @@
 <script lang="ts">
 import { defineComponent } from 'vue'
 import { useQuery } from '@tanstack/vue-query'
-import { experimental_createPersister } from '@tanstack/query-persist-client-core'
+import { experimental_createQueryPersister } from '@tanstack/query-persist-client-core'
 
 import { Post } from './types'
 
@@ -34,9 +34,9 @@ export default defineComponent({
     } = useQuery({
       queryKey: ['posts'] as const,
       queryFn: () => fetcher(),
-      persister: experimental_createPersister({
+      persister: experimental_createQueryPersister({
         storage: localStorage,
-      }),
+      }).persisterFn,
       staleTime: 5000,
     })
 

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

@@ -2,7 +2,7 @@ import { describe, expect, test, vi } from 'vitest'
 import { Query, QueryCache, hashKey } from '@tanstack/query-core'
 import {
   PERSISTER_KEY_PREFIX,
-  experimental_createPersister,
+  experimental_createQueryPersister,
 } from '../createPersister'
 import { sleep } from './utils'
 import type { StoragePersisterOptions } from '../createPersister'
@@ -12,10 +12,10 @@ function getFreshStorage() {
   const storage = new Map()
   return {
     getItem: (key: string) => Promise.resolve(storage.get(key)),
-    setItem: async (key: string, value: unknown) => {
+    setItem: (key: string, value: unknown) => {
       storage.set(key, value)
     },
-    removeItem: async (key: string) => {
+    removeItem: (key: string) => {
       storage.delete(key)
     },
   }
@@ -36,7 +36,7 @@ function setupPersister(
 
   const queryFn = vi.fn()
 
-  const persisterFn = experimental_createPersister(persisterOptions)
+  const { persisterFn } = experimental_createQueryPersister(persisterOptions)
 
   const query = new Query({
     cache: new QueryCache(),
@@ -202,7 +202,7 @@ describe('createPersister', () => {
       storageKey,
       JSON.stringify({
         buster: '',
-        state: { dataUpdatedAt },
+        state: { dataUpdatedAt, data: '' },
       }),
     )
 
@@ -231,7 +231,7 @@ describe('createPersister', () => {
       storageKey,
       JSON.stringify({
         buster: '',
-        state: { dataUpdatedAt: Date.now() },
+        state: { dataUpdatedAt: Date.now(), data: '' },
       }),
     )
 
@@ -325,7 +325,7 @@ describe('createPersister', () => {
       storageKey,
       JSON.stringify({
         buster: '',
-        state: { dataUpdatedAt: Date.now() },
+        state: { dataUpdatedAt: Date.now(), data: '' },
       }),
     )