@qiaopeng/tanstack-query-plus 0.2.1 → 0.2.3

package/README.md

@@ -126,6 +126,7 @@ function App() {
   enableOfflineSupport={true} // 启用离线状态监听（默认 true）
   cacheKey="my-app-cache"     // 自定义缓存 key（默认 'tanstack-query-cache'）
   onPersistRestore={() => console.log('缓存已恢复')}  // 缓存恢复回调
+  onPersistError={(err) => console.error('持久化错误', err)}
 >
   <YourApp />
 </PersistQueryClientProvider>
@@ -150,15 +151,15 @@ function App() {
 ```typescript
 {
   queries: {
-    staleTime: 30000,        // 数据 30 秒内视为新鲜
-    gcTime: 600000,          // 缓存保留 10 分钟
-    retry: smartRetry,       // 智能重试（4xx 不重试，5xx 最多重试 3 次）
-    retryDelay: exponential, // 指数退避（1s, 2s, 4s...最大 30s）
-    refetchOnWindowFocus: true,   // 窗口聚焦时刷新
-    refetchOnReconnect: true,     // 网络恢复时刷新
+    staleTime: 30000,
+    gcTime: 600000,
+    retry: defaultQueryRetryStrategy,
+    retryDelay: exponentialBackoff,
+    refetchOnWindowFocus: true,
+    refetchOnReconnect: true,
   },
   mutations: {
-    retry: 0,                // mutation 默认不重试
+    retry: 0,
     gcTime: 600000,
   }
 }
@@ -1040,6 +1041,52 @@ function TodoApp() {
 }
 ```
 
+### 7.10 跨分页一致性：前缀失效与缓存对齐
+
+在分页列表中，乐观更新通常只更新“当前页”的缓存。为了保证切换到其他页时也看到最新数据，可以使用前缀级失效与跨页缓存对齐：
+
+1. 使用统一的域前缀管理 Query Key（例如 `products` 域）：
+
+```tsx
+import { createDomainKeyFactory } from '@qiaopeng/tanstack-query-plus/core'
+
+const productKeys = createDomainKeyFactory('products')
+const listPrefix = productKeys.lists()            // ['tanstack-query', 'products', 'list']
+```
+
+2. 在 mutation 的乐观更新中启用跨页对齐与前缀失效：
+
+```tsx
+import { useMutation } from '@qiaopeng/tanstack-query-plus/hooks'
+
+function UpdateProduct({ product }) {
+  const mutation = useMutation({
+    mutationFn: (patch) => api.updateProduct(product.id, patch),
+    optimistic: {
+      queryKey: productKeys.detail(product.id),
+      updater: (oldData, patch) => ({ ...oldData, ...patch }),
+      invalidateScope: 'prefix',
+      invalidatePrefixKey: listPrefix,
+      reconcileCachedPages: true
+    }
+  })
+
+  return (
+    <button onClick={() => mutation.mutate({ title: '新标题' })}>
+      更新商品
+    </button>
+  )
+}
+```
+
+行为说明：
+- 乐观阶段：先更新当前 key，对已缓存的所有分页列表也应用同样的更新，使切页立即看到新值。
+- 成功后：对域前缀进行失效，后续展示从服务端获取最终一致数据。
+
+注意事项：
+- 请确保分页查询的 Key 都共享同一前缀（例如通过 `createDomainKeyFactory`），否则前缀失效无法覆盖所有分页。
+- 在超大列表场景中，跨页对齐可能带来一定开销，可按需开启。
+
 现在你已经掌握了数据变更和乐观更新。接下来，让我们学习如何处理无限滚动和分页场景。
 
 ---
@@ -2479,8 +2526,9 @@ const queueManager = createOfflineQueueManager({
 })
 
 // 注册 mutation 函数（用于恢复队列时执行）
-mutationRegistry.register('updateUser', () => updateUserAPI(data))
-mutationRegistry.register('createPost', () => createPostAPI(data))
+// 注册函数签名为 () => Promise<unknown>，如需变量请使用闭包或在入队项的 mutationFn 捕获
+mutationRegistry.register('updateUser', () => updateUserAPI(savedUserData))
+mutationRegistry.register('createPost', () => createPostAPI(savedPostData))
 
 // 添加操作到队列
 async function handleUpdateUser(userData) {
@@ -2895,7 +2943,7 @@ const { data: adminEmails } = useQuery({
   queryFn: fetchUsers,
   select: selectors.compose(
     selectors.where(u => u.role === 'admin'),
-    selectors.field('email')
+    selectors.map(u => u.email)
   ),
 })
 ```
@@ -3260,12 +3308,14 @@ src/
 ```tsx
 // queries/users.ts
 import { useEnhancedQuery } from '@qiaopeng/tanstack-query-plus/hooks'
-import { queryKeys } from './keys'
+import { createDomainKeyFactory } from '@qiaopeng/tanstack-query-plus/core'
 import { fetchUser, fetchUsers } from '@/api/users'
 
+const userKeys = createDomainKeyFactory('users')
+
 export function useUser(userId: string) {
   return useEnhancedQuery({
-    queryKey: queryKeys.user(userId),
+    queryKey: userKeys.detail(userId),
     queryFn: () => fetchUser(userId),
     enabled: !!userId,
     trackPerformance: true,
@@ -3274,7 +3324,7 @@ export function useUser(userId: string) {
 
 export function useUsers(filters?: UserFilters) {
   return useEnhancedQuery({
-    queryKey: queryKeys.users(filters),
+    queryKey: userKeys.list(filters),
     queryFn: () => fetchUsers(filters),
   })
 }

package/dist/PersistQueryClientProvider.js

@@ -11,7 +11,7 @@ export function PersistQueryClientProvider({ children, client, cacheKey = "tanst
         }
     }, [enableOfflineSupport]);
     if (enablePersistence) {
-        const persister = createPersister(cacheKey);
+        const persister = createPersister(cacheKey, undefined, _onPersistError);
         if (!persister) {
             return _jsx(QueryClientProvider, { client: client, children: children });
         }

package/dist/features/persistence.d.ts

@@ -13,7 +13,7 @@ export declare function createPersistOptions(config?: Partial<PersistOptions>):
         shouldDehydrateQuery?: (query: Query) => boolean;
     };
 };
-export declare function createPersister(storageKey?: string, storage?: Storage): Persister | undefined;
+export declare function createPersister(storageKey?: string, storage?: Storage, onError?: (error: Error) => void): Persister | undefined;
 export declare function clearCache(key?: string): void;
 export declare function clearExpiredCache(key?: string, maxAge?: number): void;
 export declare function migrateToIndexedDB(localStorageKey: string | undefined, indexedDBKey: string | undefined, indexedDBStorage: Storage | {

package/dist/features/persistence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../src/features/persistence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,sCAAsC,CAAC;AAsBvF,MAAM,WAAW,cAAc;IAAG,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAAC,gBAAgB,CAAC,EAAE;QAAE,oBAAoB,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAA;KAAE,CAAA;CAAE;AAC1J,wBAAgB,oBAAoB,CAAC,MAAM,GAAE,OAAO,CAAC,cAAc,CAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE;QAAE,oBAAoB,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAA;KAAE,CAAA;CAAE,CAiBtK;AACD,wBAAgB,eAAe,CAAC,UAAU,SAAyB,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAa7G;AACD,wBAAgB,UAAU,CAAC,GAAG,SAAyB,GAAG,IAAI,CAA0D;AACxH,wBAAgB,iBAAiB,CAAC,GAAG,SAAyB,EAAE,MAAM,SAAsB,GAAG,IAAI,CAQlG;AACD,wBAAsB,kBAAkB,CAAC,eAAe,oBAAyB,EAAE,YAAY,oBAAyB,EAAE,gBAAgB,EAAE,OAAO,GAAG;IAAE,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAWlO;AACD,wBAAgB,gBAAgB,CAAC,GAAG,SAAyB,GAAG;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CASjJ;AACD,wBAAgB,eAAe,CAAC,GAAG,SAAyB,GAAG;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAA;CAAE,CAS9L;AACD,YAAY,EAAE,eAAe,EAAE,SAAS,EAAE,CAAC"}
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../src/features/persistence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,sCAAsC,CAAC;AAsBvF,MAAM,WAAW,cAAc;IAAG,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAAC,gBAAgB,CAAC,EAAE;QAAE,oBAAoB,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAA;KAAE,CAAA;CAAE;AAC1J,wBAAgB,oBAAoB,CAAC,MAAM,GAAE,OAAO,CAAC,cAAc,CAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE;QAAE,oBAAoB,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAA;KAAE,CAAA;CAAE,CAiBtK;AACD,wBAAgB,eAAe,CAAC,UAAU,SAAyB,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,SAAS,GAAG,SAAS,CAa/I;AACD,wBAAgB,UAAU,CAAC,GAAG,SAAyB,GAAG,IAAI,CAA0D;AACxH,wBAAgB,iBAAiB,CAAC,GAAG,SAAyB,EAAE,MAAM,SAAsB,GAAG,IAAI,CAQlG;AACD,wBAAsB,kBAAkB,CAAC,eAAe,oBAAyB,EAAE,YAAY,oBAAyB,EAAE,gBAAgB,EAAE,OAAO,GAAG;IAAE,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAWlO;AACD,wBAAgB,gBAAgB,CAAC,GAAG,SAAyB,GAAG;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CASjJ;AACD,wBAAgB,eAAe,CAAC,GAAG,SAAyB,GAAG;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAA;CAAE,CAS9L;AACD,YAAY,EAAE,eAAe,EAAE,SAAS,EAAE,CAAC"}

package/dist/features/persistence.js

@@ -72,7 +72,7 @@ export function createPersistOptions(config = {}) {
         }
     };
 }
-export function createPersister(storageKey = "tanstack-query-cache", storage) {
+export function createPersister(storageKey = "tanstack-query-cache", storage, onError) {
     if (typeof window === "undefined") {
         return undefined;
     }
@@ -86,18 +86,29 @@ export function createPersister(storageKey = "tanstack-query-cache", storage) {
             persistClient: async (client) => { try {
                 safeStorage.setItem(storageKey, JSON.stringify(client));
             }
-            catch { } },
+            catch (e) {
+                if (onError && e instanceof Error) {
+                    onError(e);
+                }
+            } },
             restoreClient: async () => { try {
                 const raw = safeStorage.getItem(storageKey);
                 return raw ? JSON.parse(raw) : undefined;
             }
-            catch {
+            catch (e) {
+                if (onError && e instanceof Error) {
+                    onError(e);
+                }
                 return undefined;
             } },
             removeClient: async () => { try {
                 safeStorage.removeItem(storageKey);
             }
-            catch { } }
+            catch (e) {
+                if (onError && e instanceof Error) {
+                    onError(e);
+                }
+            } }
         };
         return persister;
     }

package/dist/hooks/useMutation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useMutation.d.ts","sourceRoot":"","sources":["../../src/hooks/useMutation.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"useMutation.d.ts","sourceRoot":"","sources":["../../src/hooks/useMutation.ts"],"names":[],"mappings":"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"}

package/dist/hooks/useMutation.js

@@ -44,7 +44,14 @@ export function useMutation(options) {
                         }
                     });
                 }
-                queryClient.setQueryData(optimistic.queryKey, (oldData) => optimistic.updater(oldData, mappedVariables));
+                const safeUpdater = (oldData) => {
+                    const next = optimistic.updater(oldData, mappedVariables);
+                    return typeof next === "undefined" ? oldData : next;
+                };
+                queryClient.setQueryData(optimistic.queryKey, safeUpdater);
+                if (optimistic.reconcileCachedPages && optimistic.invalidatePrefixKey) {
+                    queryClient.setQueriesData({ queryKey: optimistic.invalidatePrefixKey }, safeUpdater);
+                }
                 const mutateCallback = onMutate;
                 const userContext = onMutate ? await mutateCallback(variables) : undefined;
                 return { previousData, userContext };
@@ -69,7 +76,8 @@ export function useMutation(options) {
             }
         };
         mutationConfig.onSuccess = (data, variables, context) => {
-            queryClient.invalidateQueries({ queryKey: optimistic.queryKey });
+            const scope = optimistic.invalidateScope === "prefix" && optimistic.invalidatePrefixKey ? optimistic.invalidatePrefixKey : optimistic.queryKey;
+            queryClient.invalidateQueries({ queryKey: scope });
             if (onSuccess) {
                 const successCallback = onSuccess;
                 successCallback(data, variables, context?.userContext);

package/dist/types/index.d.ts

@@ -18,6 +18,9 @@ export interface MutationOptions<TData, TError, TVariables, TContext = unknown>
         enabled?: boolean;
         fieldMapping?: Record<string, string>;
         rollback?: <TQueryData = unknown>(previousData: TQueryData, error: Error) => void;
+        invalidateScope?: "exact" | "prefix";
+        invalidatePrefixKey?: QueryKey;
+        reconcileCachedPages?: boolean;
     };
 }
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC1E,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,MAAM,WAAW,eAAe,CAAC,KAAK,GAAG,OAAO,EAAE,QAAQ,GAAG,OAAO;IAAI,YAAY,CAAC,EAAE,KAAK,CAAC;IAAC,WAAW,CAAC,EAAE,QAAQ,CAAC;IAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CAAE;AAC9I,MAAM,WAAW,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,GAAG,OAAO,CAAE,SAAQ,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,CAAC;IAC7I,UAAU,CAAC,EAAE;QAAE,QAAQ,EAAE,QAAQ,CAAC;QAAC,OAAO,EAAE,CAAC,UAAU,GAAG,OAAO,EAAE,OAAO,EAAE,UAAU,GAAG,SAAS,EAAE,SAAS,EAAE,UAAU,KAAK,UAAU,GAAG,SAAS,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,QAAQ,CAAC,EAAE,CAAC,UAAU,GAAG,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,CAAA;KAAE,CAAC;CACrS"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC1E,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,MAAM,WAAW,eAAe,CAAC,KAAK,GAAG,OAAO,EAAE,QAAQ,GAAG,OAAO;IAAI,YAAY,CAAC,EAAE,KAAK,CAAC;IAAC,WAAW,CAAC,EAAE,QAAQ,CAAC;IAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CAAE;AAC9I,MAAM,WAAW,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,GAAG,OAAO,CAAE,SAAQ,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,CAAC;IAC7I,UAAU,CAAC,EAAE;QAAE,QAAQ,EAAE,QAAQ,CAAC;QAAC,OAAO,EAAE,CAAC,UAAU,GAAG,OAAO,EAAE,OAAO,EAAE,UAAU,GAAG,SAAS,EAAE,SAAS,EAAE,UAAU,KAAK,UAAU,GAAG,SAAS,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,QAAQ,CAAC,EAAE,CAAC,UAAU,GAAG,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;QAAC,eAAe,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;QAAC,mBAAmB,CAAC,EAAE,QAAQ,CAAC;QAAC,oBAAoB,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAC3Y"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qiaopeng/tanstack-query-plus",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Enhanced TanStack Query toolkit: defaults, hooks, persistence, offline, utils",
   "author": "qiaopeng",
   "license": "MIT",