refactor: deprecate createSyncStoragePersister (#9316)

Author: TkDodo

docs/framework/react/plugins/createAsyncStoragePersister.md

@@ -33,7 +33,8 @@ bun add @tanstack/query-async-storage-persister @tanstack/react-query-persist-cl
 
 - Import the `createAsyncStoragePersister` function
 - Create a new asyncStoragePersister
-  - you can pass any `storage` to it that adheres to the `AsyncStorage` 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.
+  - storages that read and write synchronously, like `window.localstorage`, also adhere to the `AsyncStorage` interface and can therefore also be used with `createAsyncStoragePersister`.
 - Wrap your app by using [`PersistQueryClientProvider`](../persistQueryClient.md#persistqueryclientprovider) component.
 
 ```tsx
@@ -99,10 +100,11 @@ interface CreateAsyncStoragePersisterOptions {
   retry?: AsyncPersistRetryer
 }
 
-interface AsyncStorage {
-  getItem: (key: string) => Promise<string | 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]>>
 }
 ```
 

docs/framework/react/plugins/createSyncStoragePersister.md

@@ -3,6 +3,11 @@ id: createSyncStoragePersister
 title: createSyncStoragePersister
 ---
 
+## Deprecated
+
+This plugin is deprecated and will be removed in the next major version.
+You can simply use ['@tanstack/query-async-storage-persister'](../createAsyncStoragePersister.md) instead.
+
 ## Installation
 
 This utility comes as a separate package and is available under the `'@tanstack/query-sync-storage-persister'` import.

docs/framework/react/plugins/persistQueryClient.md

@@ -184,7 +184,7 @@ For this use-case, you can use the `PersistQueryClientProvider`. It will make su
 
 ```tsx
 import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client'
-import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister'
+import { createAsyncStoragePersister } from '@tanstack/query-async-storage-persister'
 
 const queryClient = new QueryClient({
   defaultOptions: {
@@ -194,7 +194,7 @@ const queryClient = new QueryClient({
   },
 })
 
-const persister = createSyncStoragePersister({
+const persister = createAsyncStoragePersister({
   storage: window.localStorage,
 })
 

docs/framework/vue/guides/mutations.md

@@ -81,7 +81,7 @@ const vueQueryOptions: VueQueryPluginOptions = {
   clientPersister: (queryClient) => {
     return persistQueryClient({
       queryClient,
-      persister: createSyncStoragePersister({ storage: localStorage }),
+      persister: createAsyncStoragePersister({ storage: localStorage }),
     })
   },
   clientPersisterOnSuccess: (queryClient) => {

examples/angular/basic-persister/package.json

@@ -15,7 +15,7 @@
     "@angular/platform-browser": "^20.0.0",
     "@tanstack/angular-query-experimental": "^5.81.2",
     "@tanstack/angular-query-persist-client": "^5.62.7",
-    "@tanstack/query-sync-storage-persister": "^5.81.2",
+    "@tanstack/query-async-storage-persister": "^5.81.2",
     "rxjs": "^7.8.2",
     "tslib": "^2.8.1",
     "zone.js": "0.15.0"

examples/angular/basic-persister/src/app/app.config.ts

@@ -5,10 +5,10 @@ import {
   withDevtools,
 } from '@tanstack/angular-query-experimental'
 import { withPersistQueryClient } from '@tanstack/angular-query-persist-client'
-import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister'
+import { createAsyncStoragePersister } from '@tanstack/query-async-storage-persister'
 import type { ApplicationConfig } from '@angular/core'
 
-const localStoragePersister = createSyncStoragePersister({
+const localStoragePersister = createAsyncStoragePersister({
   storage: window.localStorage,
 })
 

examples/react/basic/package.json

@@ -9,7 +9,7 @@
     "test:eslint": "eslint ./src"
   },
   "dependencies": {
-    "@tanstack/query-sync-storage-persister": "^5.81.2",
+    "@tanstack/query-async-storage-persister": "^5.81.2",
     "@tanstack/react-query": "^5.81.2",
     "@tanstack/react-query-devtools": "^5.81.2",
     "@tanstack/react-query-persist-client": "^5.81.2",

examples/react/basic/src/index.tsx

@@ -2,7 +2,7 @@ import * as React from 'react'
 import ReactDOM from 'react-dom/client'
 import { QueryClient, useQuery, useQueryClient } from '@tanstack/react-query'
 import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client'
-import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister'
+import { createAsyncStoragePersister } from '@tanstack/query-async-storage-persister'
 import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
 
 const queryClient = new QueryClient({
@@ -13,7 +13,7 @@ const queryClient = new QueryClient({
   },
 })
 
-const persister = createSyncStoragePersister({
+const persister = createAsyncStoragePersister({
   storage: window.localStorage,
 })
 

examples/react/eslint-legacy/package.json

@@ -9,7 +9,7 @@
     "test:eslint": "ESLINT_USE_FLAT_CONFIG=false eslint ./src/**/*.tsx"
   },
   "dependencies": {
-    "@tanstack/query-sync-storage-persister": "^5.81.2",
+    "@tanstack/query-async-storage-persister": "^5.81.2",
     "@tanstack/react-query": "^5.81.2",
     "@tanstack/react-query-devtools": "^5.81.2",
     "@tanstack/react-query-persist-client": "^5.81.2",

examples/react/eslint-legacy/src/index.tsx

@@ -2,7 +2,7 @@ import * as React from 'react'
 import ReactDOM from 'react-dom/client'
 import { QueryClient, useQuery, useQueryClient } from '@tanstack/react-query'
 import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client'
-import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister'
+import { createAsyncStoragePersister } from '@tanstack/query-async-storage-persister'
 import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
 
 const queryClient = new QueryClient({
@@ -13,7 +13,7 @@ const queryClient = new QueryClient({
   },
 })
 
-const persister = createSyncStoragePersister({
+const persister = createAsyncStoragePersister({
   storage: window.localStorage,
 })