@qiaopeng/tanstack-query-plus 0.5.8 → 0.5.10

package/README.md

@@ -12,15 +12,16 @@
 6. [第四步：管理 Query Key](#6-第四步管理-query-key)
 7. [第五步：数据变更与乐观更新](#7-第五步数据变更与乐观更新)
 8. [第六步：无限滚动与分页](#8-第六步无限滚动与分页)
-9. [第七步：批量查询与仪表盘](#9-第七步批量查询与仪表盘)
-10. [第八步：智能预取](#10-第八步智能预取)
-11. [第九步：Suspense 模式](#11-第九步suspense-模式)
-12. [第十步：离线支持与持久化](#12-第十步离线支持与持久化)
-13. [第十一步：数据防护与安全](#13-第十一步数据防护与安全)
-14. [第十二步：焦点管理](#14-第十二步焦点管理)
-15. [第十三步：工具函数与选择器](#15-第十三步工具函数与选择器)
-16. [最佳实践与常见问题](#16-最佳实践与常见问题)
-17. [API 索引](#17-api-索引)
+9. [第七步：全局状态与 Mutation 监控](#9-第七步全局状态与-mutation-监控)
+10. [第八步：批量查询与仪表盘](#10-第八步批量查询与仪表盘)
+11. [第九步：智能预取](#11-第九步智能预取)
+12. [第十步：Suspense 模式与 SSR](#12-第十步suspense-模式与-ssr)
+13. [第十一步：离线支持与持久化](#13-第十一步离线支持与持久化)
+14. [第十二步：数据防护与安全](#14-第十二步数据防护与安全)
+15. [第十三步：焦点管理](#15-第十三步焦点管理)
+16. [第十四步：工具函数与选择器](#16-第十四步工具函数与选择器)
+17. [最佳实践与常见问题](#17-最佳实践与常见问题)
+18. [API 索引](#18-api-索引)
 
 ---
 
@@ -295,9 +296,11 @@ function App() {
     retryDelay: exponentialBackoff,
     refetchOnWindowFocus: true,
     refetchOnReconnect: true,
+    refetchOnMount: true,
   },
   mutations: {
     retry: 0,  // Mutation 默认不重试
+    retryDelay: exponentialBackoff,
     gcTime: 600000,
   }
 }
@@ -325,7 +328,13 @@ function App() {
 import { getConfigByEnvironment } from '@qiaopeng/tanstack-query-plus/core'
 
 // 根据环境自动选择配置
-const config = getConfigByEnvironment(process.env.NODE_ENV)
+const env =
+  process.env.NODE_ENV === 'production'
+    ? 'production'
+    : process.env.NODE_ENV === 'test'
+      ? 'test'
+      : 'development'
+const config = getConfigByEnvironment(env)
 const queryClient = new QueryClient({ defaultOptions: config })
 ```
 
@@ -340,6 +349,8 @@ const queryClient = new QueryClient({ defaultOptions: config })
 
 *智能重试：4XX 不重试，5XX 最多 1 次，网络错误最多 2 次
 
+补充：还支持 `getConfigByEnvironment('longCache')` 与 `getConfigByEnvironment('realtime')` 两种预设，分别适用于“长缓存”与“高实时”场景。
+
 ### 3.5 自定义重试策略
 
 如果默认的重试策略不满足你的需求，可以使用 `createSafeRetryStrategy` 和 `createErrorSafeConfig` 来自定义：
@@ -1129,13 +1140,21 @@ batchDelete.mutate(['id1', 'id2', 'id3'])
 2. 使用离线队列在恢复网络后批量执行（稳健且可持久化）：
 
 ```tsx
-import { createOfflineQueueManager, mutationRegistry } from '@qiaopeng/tanstack-query-plus/features'
+import { createOfflineQueueManager, mutationRegistry, serializeMutationKey } from '@qiaopeng/tanstack-query-plus/features'
+import { MutationOperationType } from '@qiaopeng/tanstack-query-plus/types'
 
 const queue = createOfflineQueueManager({ storageKey: 'todo-ops', concurrency: 3 })
 
-function registerDelete(id: string) {
-  mutationRegistry.register(['todos','delete',id].join('-'), () => api.deleteTodo(id))
-  queue.add({ mutationKey: ['todos','delete',id], mutationFn: () => api.deleteTodo(id), priority: 1 })
+async function registerDelete(id: string) {
+  const key = serializeMutationKey(['todos', 'delete', id])
+  mutationRegistry.register(key, () => api.deleteTodo(id))
+  await queue.add({
+    type: MutationOperationType.DELETE,
+    mutationKey: ['todos', 'delete', id],
+    variables: { id },
+    mutationFn: () => api.deleteTodo(id),
+    priority: 1
+  })
 }
 ```
 
@@ -1613,7 +1632,62 @@ const result = useEnhancedInfiniteQuery(customOptions)
 
 ---
 
-## 9. 第七步：批量查询与仪表盘
+## 9. 第七步：全局状态与 Mutation 监控
+
+在复杂的应用中，你可能需要监控全局的加载状态，或者获取正在进行的 Mutation 进度。本库补全了 v5 的状态监控 Hooks。
+
+### 9.1 监控全局加载状态
+
+使用 `useIsFetching` 和 `useIsMutating` 可以实时感知后台活动：
+
+```tsx
+import { useIsFetching, useIsMutating } from '@qiaopeng/tanstack-query-plus/hooks'
+
+function GlobalLoadingIndicator() {
+  const isFetching = useIsFetching() // 正在进行的 Query 数量
+  const isMutating = useIsMutating() // 正在进行的 Mutation 数量
+
+  if (!isFetching && !isMutating) return null
+
+  return (
+    <div className="fixed top-0 right-0 p-4">
+      {isFetching > 0 && <span>数据加载中...</span>}
+      {isMutating > 0 && <span>后台同步中...</span>}
+    </div>
+  )
+}
+```
+
+### 9.2 监控 Mutation 详细状态
+
+`useMutationState` 允许你订阅 Mutation 缓存，获取特定任务的进度或结果：
+
+```tsx
+import { useMutationState } from '@qiaopeng/tanstack-query-plus/hooks'
+
+function UploadManager() {
+  // 获取所有 ['upload'] 相关的 mutation 状态
+  const uploads = useMutationState({
+    filters: { mutationKey: ['upload'], status: 'pending' },
+    select: (mutation) => mutation.state.variables,
+  })
+
+  return (
+    <div>
+      <h3>正在上传 ({uploads.length})</h3>
+      <ul>
+        {uploads.map((file, i) => (
+          <li key={i}>{file.name} 正在传输...</li>
+        ))}
+      </ul>
+    </div>
+  )
+}
+```
+
+---
+
+## 10. 第八步：批量查询与仪表盘
 
 
 在仪表盘、数据概览等场景中，我们经常需要同时发起多个查询。本库提供了强大的批量查询功能，包括统计信息、批量操作和错误聚合。
@@ -2266,74 +2340,49 @@ function ProductBrowser() {
 
 ---
 
-## 11. 第九步：Suspense 模式
+## 12. 第十步：Suspense 模式与 SSR
 
+React Suspense 提供了声明式的加载处理。本库不仅支持增强的 Suspense Hooks，还提供了完善的 SSR 水合支持。
 
-React Suspense 是一种声明式的加载状态处理方式。配合 TanStack Query 的 Suspense 模式，可以让组件代码更简洁，不再需要手动处理 `isLoading` 状态。
+### 12.1 基础 Suspense 查询
 
-### 11.1 传统模式 vs Suspense 模式
+`useEnhancedSuspenseQuery` 保证 `data` 始终存在，省去非空判断：
 
-**传统模式：**
 ```tsx
-function UserProfile({ userId }) {
-  const { data, isLoading, isError, error } = useQuery({
-    queryKey: ['user', userId],
-    queryFn: () => fetchUser(userId),
-  })
-
-  if (isLoading) return <Loading />
-  if (isError) return <Error message={error.message} />
-  
-  return <div>{data.name}</div>
-}
-```
+import { useEnhancedSuspenseQuery } from '@qiaopeng/tanstack-query-plus/hooks'
 
-**Suspense 模式：**
-```tsx
 function UserProfile({ userId }) {
-  // 数据一定存在，不需要处理 loading 状态
-  const { data } = useSuspenseQuery({
+  const { data } = useEnhancedSuspenseQuery({
     queryKey: ['user', userId],
     queryFn: () => fetchUser(userId),
   })
   
   return <div>{data.name}</div>
 }
-
-// 在父组件处理 loading 和 error
-function UserPage({ userId }) {
-  return (
-    <Suspense fallback={<Loading />}>
-      <ErrorBoundary fallback={<Error />}>
-        <UserProfile userId={userId} />
-      </ErrorBoundary>
-    </Suspense>
-  )
-}
 ```
 
-### 11.2 使用增强 Suspense 查询
+### 12.2 SSR 水合支持
+
+在 Next.js (App Router) 或其他 SSR 框架中，使用 `HydrationBoundary` 进行注水：
 
 ```tsx
-import { useEnhancedSuspenseQuery } from '@qiaopeng/tanstack-query-plus/hooks'
+// Server Component
+import { dehydrate, QueryClient } from '@qiaopeng/tanstack-query-plus'
+import { HydrationBoundary } from '@qiaopeng/tanstack-query-plus/components'
 
-function UserData({ userId }) {
-  const { data } = useEnhancedSuspenseQuery({
-    queryKey: ['user', userId],
-    queryFn: () => fetchUser(userId),
-  })
+export default async function Page() {
+  const queryClient = new QueryClient()
+  await queryClient.prefetchQuery({ queryKey: ['posts'], queryFn: fetchPosts })
 
-  // data 一定存在，TypeScript 类型也是非空的
   return (
-    <div>
-      <h1>{data.name}</h1>
-      <p>{data.email}</p>
-    </div>
+    <HydrationBoundary state={dehydrate(queryClient)}>
+      <PostsList />
+    </HydrationBoundary>
   )
 }
 ```
 
-### 11.3 使用 SuspenseWrapper 组件
+### 12.3 使用 SuspenseWrapper 组件
 
 本库提供了 `SuspenseWrapper` 和 `QuerySuspenseWrapper` 组件，它们组合了 Suspense 和 ErrorBoundary：
 
@@ -2710,7 +2759,8 @@ console.log({
 对于需要在离线时也能操作的应用，可以使用离线队列管理器：
 
 ```tsx
-import { createOfflineQueueManager, mutationRegistry } from '@qiaopeng/tanstack-query-plus/features'
+import { createOfflineQueueManager, isOnline, mutationRegistry, serializeMutationKey } from '@qiaopeng/tanstack-query-plus/features'
+import { MutationOperationType } from '@qiaopeng/tanstack-query-plus/types'
 
 // 创建队列管理器
 const queueManager = createOfflineQueueManager({
@@ -2723,15 +2773,17 @@ const queueManager = createOfflineQueueManager({
 
 // 注册 mutation 函数（用于恢复队列时执行）
 // 注册函数签名为 () => Promise<unknown>，如需变量请使用闭包或在入队项的 mutationFn 捕获
-mutationRegistry.register('updateUser', () => updateUserAPI(savedUserData))
-mutationRegistry.register('createPost', () => createPostAPI(savedPostData))
+mutationRegistry.register(serializeMutationKey(['updateUser']), () => updateUserAPI(savedUserData))
+mutationRegistry.register(serializeMutationKey(['createPost']), () => createPostAPI(savedPostData))
 
 // 添加操作到队列
 async function handleUpdateUser(userData) {
   if (!isOnline()) {
     // 离线时添加到队列
     await queueManager.add({
+      type: MutationOperationType.UPDATE,
       mutationKey: ['updateUser'],
+      variables: userData,
       mutationFn: () => updateUserAPI(userData),
       priority: 1,  // 优先级（数字越大越优先）
     })
@@ -2772,6 +2824,7 @@ queueManager.destroy()
 ```tsx
 import { useState, useEffect } from 'react'
 import { createOfflineQueueManager } from '@qiaopeng/tanstack-query-plus/features'
+import { MutationOperationType } from '@qiaopeng/tanstack-query-plus/types'
 import { useEnhancedQuery } from '@qiaopeng/tanstack-query-plus/hooks'
 import { useQueryClient, usePersistenceStatus } from '@qiaopeng/tanstack-query-plus'
 
@@ -2817,7 +2870,9 @@ function TodoApp() {
     if (!networkStatus) {
       // 离线：添加到队列
       await offlineQueue.add({
+        type: MutationOperationType.CREATE,
         mutationKey: ['addTodo'],
+        variables: todoData,
         mutationFn: () => api.createTodo(todoData),
         priority: 1,
       })
@@ -3675,7 +3730,13 @@ function UserProfile({ userId }) {
 import { QueryClient } from '@qiaopeng/tanstack-query-plus'
 import { getConfigByEnvironment, ensureBestPractices } from '@qiaopeng/tanstack-query-plus/core'
 
-const baseConfig = getConfigByEnvironment(process.env.NODE_ENV)
+const env =
+  process.env.NODE_ENV === 'production'
+    ? 'production'
+    : process.env.NODE_ENV === 'test'
+      ? 'test'
+      : 'development'
+const baseConfig = getConfigByEnvironment(env)
 
 // 确保配置符合最佳实践
 const config = ensureBestPractices({
@@ -3751,12 +3812,12 @@ function useUser(userId: string): EnhancedQueryResult<User, ApiError> {
 }
 
 // 类型安全的 mutation
-function useUpdateUser() {
+function useUpdateUser(userId: string) {
   return useMutation<User, ApiError, Partial<User>>({
-    mutationFn: (data) => updateUser(data),
+    mutationFn: (patch) => updateUser(userId, patch),
     optimistic: {
-      queryKey: ['user', data.id],
-      updater: (old, newData) => ({ ...old, ...newData }),
+      queryKey: ['user', userId],
+      updater: (old, patch) => (old ? ({ ...old, ...patch }) : old),
     },
   })
 }
@@ -3886,32 +3947,6 @@ useEnhancedQuery({
 3. **处理认证过期**：在全局错误处理中处理 401 错误
 4. **清理敏感缓存**：用户登出时清除缓存
 
----
-
-## 总结
-
-恭喜你完成了本教程！现在你已经掌握了 `@qiaopeng/tanstack-query-plus` 的所有核心功能：
-
-1. ✅ 配置 Provider 和最佳实践
-2. ✅ 基础查询和增强查询
-3. ✅ Query Key 管理
-4. ✅ 数据变更和乐观更新
-5. ✅ 无限滚动和分页
-6. ✅ 批量查询和仪表盘
-7. ✅ 智能预取策略
-8. ✅ Suspense 模式
-9. ✅ 离线支持和持久化
-10. ✅ 数据防护与安全
-11. ✅ 焦点管理
-12. ✅ 工具函数和选择器
-
-### 下一步
-
-- 查看 [GitHub 仓库](https://github.com/qiaopengg/qiaopeng-tanstack-query-plus) 获取最新更新
-- 阅读 [TanStack Query 官方文档](https://tanstack.com/query/latest) 了解更多底层概念
-- 在 [Issues](https://github.com/qiaopengg/qiaopeng-tanstack-query-plus/issues) 中提问或反馈
-
-祝你编码愉快！🚀
 ### 16.9 类型与错误处理规范
 
 - 明确类型参数：在增强 hooks 中显式标注 `TData` 与 `TError`，避免 `any` 漏出
@@ -3979,13 +4014,13 @@ useEnhancedQuery({
   - 数据防护：`useDataGuardQueryConfig`、`useDataGuardMutation`
 
 - `@qiaopeng/tanstack-query-plus/features`
-  - 离线：`setupOnlineManager`、`isOnline`、`createOfflineQueueManager`、`OfflineQueueManager`、`mutationRegistry`、`subscribeToOnlineStatus`
+  - 离线：`setupOnlineManager`、`isOnline`、`createOfflineQueueManager`、`OfflineQueueManager`、`mutationRegistry`、`serializeMutationKey`、`subscribeToOnlineStatus`
   - 持久化：`createPersistOptions`、`createPersister`、`clearCache`、`clearExpiredCache`、`checkStorageSize`、`getStorageStats`、`migrateToIndexedDB`
 
 - `@qiaopeng/tanstack-query-plus/components`
   - Loading：`DefaultLoadingFallback`、`FullScreenLoading`、`ListSkeletonFallback`、`PageSkeletonFallback`、`SmallLoadingIndicator`、`TextSkeletonFallback`
   - 错误边界：`QueryErrorBoundary`
-  - Suspense：`SuspenseWrapper`、`QuerySuspenseWrapper`
+  - Suspense & SSR：`SuspenseWrapper`、`QuerySuspenseWrapper`、`HydrationBoundary`
 
 - `@qiaopeng/tanstack-query-plus/utils`
   - 选择器：`selectById`、`selectFields`、`compose` 等
@@ -3999,3 +4034,28 @@ useEnhancedQuery({
   - 原生 API 再导出：`useQuery`、`useMutation`、`useInfiniteQuery`、`useSuspenseQuery` 等（src/react-query/index.ts:1）
 
 提示：完整导出列表可在 `package.json:33` 的 `exports` 字段中查看；顶层入口再导出常用原生 API，子路径按模块分层导出，便于 tree-shaking。
+
+---
+
+## 总结
+
+你已经覆盖了 `@qiaopeng/tanstack-query-plus` 的核心能力：
+
+1. ✅ 配置 Provider 和最佳实践
+2. ✅ 基础查询和增强查询
+3. ✅ Query Key 管理
+4. ✅ 数据变更和乐观更新
+5. ✅ 无限滚动和分页
+6. ✅ 批量查询和仪表盘
+7. ✅ 智能预取策略
+8. ✅ Suspense 模式
+9. ✅ 离线支持和持久化
+10. ✅ 数据防护与安全
+11. ✅ 焦点管理
+12. ✅ 工具函数和选择器
+
+### 下一步
+
+- 查看 [GitHub 仓库](https://github.com/qiaopengg/qiaopeng-tanstack-query-plus) 获取最新更新
+- 阅读 [TanStack Query 官方文档](https://tanstack.com/query/latest) 了解更多底层概念
+- 在 [Issues](https://github.com/qiaopengg/qiaopeng-tanstack-query-plus/issues) 中提问或反馈

package/dist/{types/base.d.ts → base-CHnwqfyz.d.cts}

@@ -1,41 +1,39 @@
-import type { QueryClient } from "@tanstack/react-query";
-import type { PersistedClient, Persister } from "@tanstack/react-query-persist-client";
-export declare enum StorageType {
+declare enum StorageType {
     LOCAL = "localStorage",
     SESSION = "sessionStorage",
     INDEXED_DB = "indexedDB",
     CUSTOM = "custom"
 }
-export declare enum ConnectionQuality {
+declare enum ConnectionQuality {
     SLOW = "slow",
     FAST = "fast",
     UNKNOWN = "unknown"
 }
-export declare enum CachePriority {
+declare enum CachePriority {
     HIGH = "high",
     MEDIUM = "medium",
     LOW = "low"
 }
-export declare enum PersistenceStrategyType {
+declare enum PersistenceStrategyType {
     AGGRESSIVE = "aggressive",
     CONSERVATIVE = "conservative",
     SELECTIVE = "selective",
     CUSTOM = "custom"
 }
-export interface OperationResult<T = unknown> {
+interface OperationResult<T = unknown> {
     success: boolean;
     data?: T;
     error?: Error;
     duration?: number;
     metadata?: Record<string, unknown>;
 }
-export interface NetworkInformation {
+interface NetworkInformation {
     effectiveType?: "4g" | "3g" | "2g" | "slow-2g";
     saveData?: boolean;
     downlink?: number;
     rtt?: number;
 }
-export interface NetworkStatus {
+interface NetworkStatus {
     isOnline: boolean;
     isOffline: boolean;
     connectionQuality: ConnectionQuality;
@@ -43,12 +41,12 @@ export interface NetworkStatus {
     lastOnlineAt?: Date;
     lastOfflineAt?: Date;
 }
-export type DeepReadonly<T> = {
+type DeepReadonly<T> = {
     readonly [P in keyof T]: T[P] extends object ? DeepReadonly<T[P]> : T[P];
 };
-export type Optional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
-export type Required<T, K extends keyof T> = T & {
+type Optional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+type Required<T, K extends keyof T> = T & {
     [P in K]-?: T[P];
 };
-export type { PersistedClient, Persister, QueryClient };
-//# sourceMappingURL=base.d.ts.map
+
+export { ConnectionQuality as C, type DeepReadonly as D, type NetworkInformation as N, type OperationResult as O, PersistenceStrategyType as P, type Required as R, StorageType as S, CachePriority as a, type NetworkStatus as b, type Optional as c };

package/dist/base-CHnwqfyz.d.ts

@@ -0,0 +1,52 @@
+declare enum StorageType {
+    LOCAL = "localStorage",
+    SESSION = "sessionStorage",
+    INDEXED_DB = "indexedDB",
+    CUSTOM = "custom"
+}
+declare enum ConnectionQuality {
+    SLOW = "slow",
+    FAST = "fast",
+    UNKNOWN = "unknown"
+}
+declare enum CachePriority {
+    HIGH = "high",
+    MEDIUM = "medium",
+    LOW = "low"
+}
+declare enum PersistenceStrategyType {
+    AGGRESSIVE = "aggressive",
+    CONSERVATIVE = "conservative",
+    SELECTIVE = "selective",
+    CUSTOM = "custom"
+}
+interface OperationResult<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: Error;
+    duration?: number;
+    metadata?: Record<string, unknown>;
+}
+interface NetworkInformation {
+    effectiveType?: "4g" | "3g" | "2g" | "slow-2g";
+    saveData?: boolean;
+    downlink?: number;
+    rtt?: number;
+}
+interface NetworkStatus {
+    isOnline: boolean;
+    isOffline: boolean;
+    connectionQuality: ConnectionQuality;
+    connection?: NetworkInformation;
+    lastOnlineAt?: Date;
+    lastOfflineAt?: Date;
+}
+type DeepReadonly<T> = {
+    readonly [P in keyof T]: T[P] extends object ? DeepReadonly<T[P]> : T[P];
+};
+type Optional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+type Required<T, K extends keyof T> = T & {
+    [P in K]-?: T[P];
+};
+
+export { ConnectionQuality as C, type DeepReadonly as D, type NetworkInformation as N, type OperationResult as O, PersistenceStrategyType as P, type Required as R, StorageType as S, CachePriority as a, type NetworkStatus as b, type Optional as c };