@qiaopeng/tanstack-query-plus 0.4.3 → 0.5.0

package/README.md

@@ -1042,55 +1042,6 @@ function TodoApp() {
 }
 ```
 
-### 7.10 分页家族一致性（避免分页切换回退）
-
-在带分页/筛选/排序的列表中，编辑、新增、删除、状态变更成功后切换 `page/pageSize` 时，可能命中同一资源的另一查询变体，从而短暂显示旧快照。本库提供可选的“家族一致性”能力，保障在成功后切换分页不回退。
-
-- 开启方式：在 `useMutation` 传入 `consistency` 配置
-- 默认策略：`mode: 'sync+invalidate'` 先同步更新缓存，再延迟失效，确保 UI 立即响应且最终一致
-- 安全策略：`mode: 'invalidate-only'` 仅执行失效，完全依赖服务端数据（适合非关键数据）
-- 形状适配：通过 `consistency.familySync.listSelector` 适配 `{items,total}` 结构；无法识别时自动降级为仅失效
-
-```tsx
-import { useMutation } from '@qiaopeng/tanstack-query-plus/hooks'
-import { createPaginatedKey } from '@qiaopeng/tanstack-query-plus/core'
-
-function useUpdateProduct({ page, pageSize }) {
-  return useMutation({
-    mutationFn: (updated) => api.updateProduct(updated.id, updated),
-
-    // 当前页的乐观更新：先更新 UI，再发请求，失败自动回滚
-    optimistic: {
-      queryKey: createPaginatedKey(['products', 'list'], page, pageSize),
-      updater: (old, updated) => old?.map((p) => (p.id === updated.id ? { ...p, ...updated } : p)),
-    },
-
-    // 家族一致性：编辑成功后，保障跨分页/筛选/排序的变体不回退
-    consistency: {
-      mode: 'sync+invalidate', // 默认值，先同步缓存再延迟失效
-      invalidationDelay: 1000, // 延迟失效，等待后端一致性
-      familySync: {
-        idField: 'id',
-        // 适配分页对象：提取 items；不确定时返回 null 将仅失效
-        listSelector: (data) => {
-          if (data && typeof data === 'object' && 'items' in (data as any)) {
-            return { items: (data as any).items, total: (data as any).total }
-          }
-          if (Array.isArray(data)) return { items: data }
-          return null
-        },
-        maxKeys: 50,
-      }
-    },
-  })
-}
-```
-
-适用操作与行为说明：
-- 编辑/删除：在 `sync+invalidate` 模式下，会对已缓存的家族变体按 `id` 合并或移除；随后统一失效，最终以服务端为准
-- **自动竞态保护**：当检测到 `consistency` 模式开启时，会自动取消该列表家族下所有正在进行的旧请求，防止旧数据覆盖新缓存
-- 新增/状态变更：默认不做跨页注入，仅当前页处理并家族失效；需要跨页放置时请在服务端裁决归属
-
 现在你已经掌握了数据变更和乐观更新。接下来，让我们学习如何处理无限滚动和分页场景。
 
 ---

package/dist/hooks/useDataGuardMutation.d.ts

@@ -28,10 +28,6 @@ export interface DataGuardMutationOptions<TData, TError, TVariables, TContext> e
  *         items: old?.items?.map(p => p.id === updated.id ? updated : p)
  *       })
  *     },
- *     consistency: {
- *       mode: 'sync+invalidate',
- *       invalidationDelay: 3000
- *     },
  *     onConflict: (error) => {
  *       toast.error('数据冲突，请刷新')
  *     }

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

@@ -1 +1 @@
-{"version":3,"file":"useDataGuardMutation.d.ts","sourceRoot":"","sources":["../../src/hooks/useDataGuardMutation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AACzE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,eAAe,EAA8B,MAAM,uBAAuB,CAAC;AAOzF,MAAM,WAAW,wBAAwB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,CAAE,SAAQ,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,CAAC;IACzI,aAAa;IACb,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,IAAI,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,SAAS,eAAe,GAAG,eAAe,EAC/C,MAAM,GAAG,KAAK,EACd,UAAU,SAAS,eAAe,GAAG,eAAe,EACpD,QAAQ,GAAG,OAAO,EAElB,UAAU,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,OAAO,CAAC,KAAK,CAAC,EAChD,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE,wBAAwB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,CAAC,GACtE,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,CAAC,CAmHxD"}
+{"version":3,"file":"useDataGuardMutation.d.ts","sourceRoot":"","sources":["../../src/hooks/useDataGuardMutation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AACzE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,eAAe,EAA8B,MAAM,uBAAuB,CAAC;AAuBzF,MAAM,WAAW,wBAAwB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,CAAE,SAAQ,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,CAAC;IACzI,aAAa;IACb,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,IAAI,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,SAAS,eAAe,GAAG,eAAe,EAC/C,MAAM,GAAG,KAAK,EACd,UAAU,SAAS,eAAe,GAAG,eAAe,EACpD,QAAQ,GAAG,OAAO,EAElB,UAAU,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,OAAO,CAAC,KAAK,CAAC,EAChD,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE,wBAAwB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,CAAC,GACtE,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,CAAC,CAkHxD"}

package/dist/hooks/useDataGuardMutation.js

@@ -2,7 +2,21 @@ import { useQueryClient } from "@tanstack/react-query";
 import { useMutation } from "./useMutation.js";
 import { ConflictError } from "../types/dataGuard.js";
 import { hashObject, markRecentlyUpdated, clearRecentlyUpdated, updateFamilyMetadata } from "../utils/dataGuard.js";
-import { startsWithKeyPrefix } from "../utils/consistency.js";
+/**
+ * Check if a query key starts with a given prefix
+ */
+function startsWithKeyPrefix(key, prefix) {
+    const k = Array.isArray(key) ? key : [key];
+    const p = Array.isArray(prefix) ? prefix : [prefix];
+    if (p.length > k.length)
+        return false;
+    for (let i = 0; i < p.length; i++) {
+        if (JSON.stringify(k[i]) !== JSON.stringify(p[i])) {
+            return false;
+        }
+    }
+    return true;
+}
 /**
  * 带数据防护的 Mutation Hook
  *
@@ -26,10 +40,6 @@ import { startsWithKeyPrefix } from "../utils/consistency.js";
  *         items: old?.items?.map(p => p.id === updated.id ? updated : p)
  *       })
  *     },
- *     consistency: {
- *       mode: 'sync+invalidate',
- *       invalidationDelay: 3000
- *     },
  *     onConflict: (error) => {
  *       toast.error('数据冲突，请刷新')
  *     }
@@ -91,9 +101,8 @@ export function useDataGuardMutation(mutationFn, queryKey, options) {
             // 更新所有家族缓存的元数据
             const familyKey = Array.isArray(queryKey) ? queryKey.slice(0, -1) : [queryKey];
             updateFamilyMetadata(queryClient, familyKey, data);
-            // 计算清理延迟时间（基于 invalidationDelay + 缓冲时间）
-            const invalidationDelay = options?.consistency?.invalidationDelay || 3000;
-            const cleanupDelay = invalidationDelay + 2000; // 在失效后2秒清理
+            // 延迟清理最近更新标记（5秒后）
+            const cleanupDelay = 5000;
             // 延迟清理最近更新标记
             setTimeout(() => {
                 try {

package/dist/hooks/useMutation.d.ts

@@ -2,7 +2,6 @@ import type { MutationFunction, MutationKey, QueryClient, QueryKey, UseMutationO
 import type { MutationOptions } from "../types";
 import type { EntityWithId } from "../types/selectors";
 export type { MutationKey };
-import { FamilySyncConfig } from "../utils/consistency.js";
 export interface MutationDefaultsConfig {
     [key: string]: TanStackUseMutationOptions<any, any, any, any>;
 }
@@ -14,17 +13,11 @@ export declare function setupMutationDefaults(queryClient: QueryClient, config:
 export declare function useListMutation<T extends EntityWithId>(mutationFn: MutationFunction<T, {
     operation: string;
     data: Partial<T>;
-}>, queryKey: QueryKey, options?: (TanStackUseMutationOptions<T, Error, {
+}>, queryKey: QueryKey, options?: TanStackUseMutationOptions<T, Error, {
     operation: string;
     data: Partial<T>;
 }> & {
     mutationKey?: readonly unknown[];
-}) & {
-    consistency?: {
-        familySync?: FamilySyncConfig;
-        mode?: "sync+invalidate" | "invalidate-only" | "sync-only" | "auto";
-        invalidationDelay?: number;
-    };
 }): UseMutationResult<T, Error, {
     operation: string;
     data: Partial<T>;

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

@@ -1 +1 @@
-{"version":3,"file":"useMutation.d.ts","sourceRoot":"","sources":["../../src/hooks/useMutation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ,EAAE,kBAAkB,IAAI,0BAA0B,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AACvK,OAAO,KAAK,EAAmB,eAAe,EAAE,MAAM,UAAU,CAAC;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGvD,YAAY,EAAE,WAAW,EAAE,CAAC;AAC5B,OAAO,EAAE,gBAAgB,EAAiF,MAAM,yBAAyB,CAAC;AAE1I,MAAM,WAAW,sBAAsB;IAAG,CAAC,GAAG,EAAE,MAAM,GAAG,0BAA0B,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAA;CAAE;AA4BzG,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,WAAW,EAAE,KAAK,EAAE,GAAG,EAAE,QAE5E;AAED,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,WAAW,EAAE,KAAK,EAAE,GAAG,EAAE,QAExE;AAED,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,WAAW,EAAE,KAAK,EAAE,GAAG,EAAE,QAEvE;AAUD,wBAAgB,WAAW,CAAC,KAAK,GAAG,OAAO,EAAE,MAAM,GAAG,KAAK,EAAE,UAAU,GAAG,IAAI,EAAE,QAAQ,GAAG,OAAO,EAAE,OAAO,EAAE,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,CAAC,GAAG,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,CAAC,CAgJzN;AAED,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,WAAW,EAAE,MAAM,EAAE,sBAAsB,GAAG,IAAI,CAEpG;AAED,wBAAgB,eAAe,CAAC,CAAC,SAAS,YAAY,EACpD,UAAU,EAAE,gBAAgB,CAAC,CAAC,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;CAAE,CAAC,EACxE,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE,CAAC,0BAA0B,CAAC,CAAC,EAAE,KAAK,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;CAAE,CAAC,GAAG;IAAE,WAAW,CAAC,EAAE,SAAS,OAAO,EAAE,CAAA;CAAE,CAAC,GAAG;IACjI,WAAW,CAAC,EAAE;QACZ,UAAU,CAAC,EAAE,gBAAgB,CAAC;QAC9B,IAAI,CAAC,EAAE,iBAAiB,GAAG,iBAAiB,GAAG,WAAW,GAAG,MAAM,CAAC;QACpE,iBAAiB,CAAC,EAAE,MAAM,CAAC;KAC5B,CAAA;CACF;eAN4D,MAAM;UAAQ,OAAO,CAAC,CAAC,CAAC;YAoCtF"}
+{"version":3,"file":"useMutation.d.ts","sourceRoot":"","sources":["../../src/hooks/useMutation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ,EAAE,kBAAkB,IAAI,0BAA0B,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AACvK,OAAO,KAAK,EAAmB,eAAe,EAAE,MAAM,UAAU,CAAC;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGvD,YAAY,EAAE,WAAW,EAAE,CAAC;AAE5B,MAAM,WAAW,sBAAsB;IAAG,CAAC,GAAG,EAAE,MAAM,GAAG,0BAA0B,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAA;CAAE;AAkBzG,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,WAAW,EAAE,KAAK,EAAE,GAAG,EAAE,QAE5E;AAED,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,WAAW,EAAE,KAAK,EAAE,GAAG,EAAE,QAExE;AAED,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,WAAW,EAAE,KAAK,EAAE,GAAG,EAAE,QAEvE;AAED,wBAAgB,WAAW,CAAC,KAAK,GAAG,OAAO,EAAE,MAAM,GAAG,KAAK,EAAE,UAAU,GAAG,IAAI,EAAE,QAAQ,GAAG,OAAO,EAAE,OAAO,EAAE,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,CAAC,GAAG,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,CAAC,CAwIzN;AAED,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,WAAW,EAAE,MAAM,EAAE,sBAAsB,GAAG,IAAI,CAEpG;AAED,wBAAgB,eAAe,CAAC,CAAC,SAAS,YAAY,EACpD,UAAU,EAAE,gBAAgB,CAAC,CAAC,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;CAAE,CAAC,EACxE,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE,0BAA0B,CAAC,CAAC,EAAE,KAAK,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;CAAE,CAAC,GAAG;IAAE,WAAW,CAAC,EAAE,SAAS,OAAO,EAAE,CAAA;CAAE;eAAlE,MAAM;UAAQ,OAAO,CAAC,CAAC,CAAC;YAarF"}

package/dist/hooks/useMutation.js

@@ -1,6 +1,5 @@
 import { useQueryClient, useMutation as useTanStackMutation } from "@tanstack/react-query";
 import { DEFAULT_MUTATION_CONFIG } from "../core/config.js";
-import { syncEntityAcrossFamily, syncEntityAcrossFamilyOptimistic, DEFAULT_FAMILY_SYNC } from "../utils/consistency.js";
 function deriveFamilyKey(queryKey) {
     const arr = Array.isArray(queryKey) ? [...queryKey] : [queryKey];
     while (arr.length > 1) {
@@ -21,18 +20,6 @@ function isListFamilyKey(queryKey) {
     const parts = Array.isArray(queryKey) ? queryKey : [queryKey];
     return parts.includes("list") || parts.includes("paginated");
 }
-function getConsistencyStrategy(mode, op) {
-    const m = mode ?? "sync+invalidate";
-    if (m === "sync-only")
-        return { sync: true, invalidate: false };
-    if (m === "invalidate-only")
-        return { sync: false, invalidate: true };
-    // Auto mode: Always sync for immediate UI feedback, and always invalidate for eventual consistency
-    // Note: The invalidation should ideally be delayed to avoid old-data flicker (handled in delay logic)
-    if (m === "auto")
-        return { sync: true, invalidate: true };
-    return { sync: true, invalidate: true };
-}
 export function invalidateQueriesBatch(queryClient, tasks) {
     tasks.forEach(task => queryClient.invalidateQueries(task));
 }
@@ -42,17 +29,9 @@ export function cancelQueriesBatch(queryClient, tasks) {
 export function setQueryDataBatch(queryClient, tasks) {
     tasks.forEach(task => queryClient.setQueryData(task.queryKey, task.data));
 }
-function executeInvalidations(queryClient, tasks) {
-    if (tasks.length === 1) {
-        queryClient.invalidateQueries(tasks[0]);
-    }
-    else if (tasks.length > 1) {
-        invalidateQueriesBatch(queryClient, tasks);
-    }
-}
 export function useMutation(options) {
     const queryClient = useQueryClient();
-    const { optimistic, onMutate, onError, onSuccess, onSettled, consistency, ...restOptions } = options;
+    const { optimistic, onMutate, onError, onSuccess, onSettled, ...restOptions } = options;
     const mutationConfig = {
         ...restOptions,
         retry: restOptions.retry ?? DEFAULT_MUTATION_CONFIG?.retry,
@@ -81,14 +60,13 @@ export function useMutation(options) {
                 return { userContext };
             }
             try {
-                await queryClient.cancelQueries({ queryKey: optimistic.queryKey, exact: true });
-                // Cancel family queries to prevent race conditions:
-                // Ensure no outdated refetches overwrite our optimistic/synced updates
-                if (consistency?.mode !== "invalidate-only") {
-                    const familyKey = optimistic.familyKey ?? deriveFamilyKey(optimistic.queryKey);
-                    await queryClient.cancelQueries({ queryKey: familyKey });
-                }
-                const previousData = queryClient.getQueryData(optimistic.queryKey);
+                // Derive family key (e.g., ['products', 'list'] from ['products', 'list', { page: 1, pageSize: 10 }])
+                const familyKey = optimistic.familyKey ?? deriveFamilyKey(optimistic.queryKey);
+                // Cancel all queries in the family to prevent race conditions
+                await queryClient.cancelQueries({ queryKey: familyKey });
+                // Save snapshots of all queries in the family
+                const previousData = queryClient.getQueriesData({ queryKey: familyKey });
+                // Apply field mapping if specified
                 let mappedVariables = variables;
                 if (optimistic.fieldMapping && typeof variables === "object" && variables !== null) {
                     mappedVariables = { ...variables };
@@ -100,36 +78,34 @@ export function useMutation(options) {
                         }
                     });
                 }
-                queryClient.setQueryData(optimistic.queryKey, (oldData) => optimistic.updater(oldData, mappedVariables));
-                let familyRollbackData = [];
-                const op = (typeof variables?.operation === "string" ? variables.operation : consistency?.defaultOperation) ?? "update";
-                const { sync } = getConsistencyStrategy(consistency?.mode, op);
-                if (sync && optimistic?.queryKey) {
-                    const familyKey = optimistic.familyKey ?? deriveFamilyKey(optimistic.queryKey);
-                    const payload = typeof variables === "object" && variables !== null ? (variables.data ?? variables) : variables;
-                    const cfg = consistency?.familySync ?? DEFAULT_FAMILY_SYNC;
-                    familyRollbackData = syncEntityAcrossFamilyOptimistic(queryClient, familyKey, cfg, op, payload);
-                }
+                // ✅ Official approach: Update all cached query variants using setQueriesData
+                queryClient.setQueriesData({ queryKey: familyKey }, (oldData) => {
+                    if (!oldData)
+                        return oldData;
+                    return optimistic.updater(oldData, mappedVariables);
+                });
                 const mutateCallback = onMutate;
                 const userContext = onMutate ? await mutateCallback(variables) : undefined;
-                return { previousData, userContext, familyRollbackData };
+                return { previousData, userContext };
             }
             catch (error) {
                 return { userContext: undefined };
             }
         };
         mutationConfig.onError = (error, variables, context) => {
-            if (context?.previousData !== undefined) {
-                queryClient.setQueryData(optimistic.queryKey, context.previousData);
-            }
-            if (context?.familyRollbackData) {
-                context.familyRollbackData.forEach(item => {
-                    queryClient.setQueryData(item.queryKey, item.previousData);
+            // Rollback all query variants
+            if (context?.previousData) {
+                context.previousData.forEach(([queryKey, data]) => {
+                    queryClient.setQueryData(queryKey, data);
                 });
             }
-            if (optimistic.rollback && context?.previousData !== undefined) {
+            if (optimistic.rollback && context?.previousData) {
                 try {
-                    optimistic.rollback(context.previousData, error);
+                    // Call rollback with the first snapshot (usually the current query)
+                    const firstSnapshot = context.previousData[0]?.[1];
+                    if (firstSnapshot) {
+                        optimistic.rollback(firstSnapshot, error);
+                    }
                 }
                 catch { }
             }
@@ -139,33 +115,26 @@ export function useMutation(options) {
             }
         };
         mutationConfig.onSuccess = (data, variables, context) => {
-            const op = (typeof variables?.operation === "string" ? variables.operation : consistency?.defaultOperation) ?? "update";
-            const { sync, invalidate } = getConsistencyStrategy(consistency?.mode, op);
-            if (sync && optimistic?.queryKey) {
-                const familyKey = optimistic.familyKey ?? deriveFamilyKey(optimistic.queryKey);
-                const payload = typeof variables === "object" && variables !== null ? (variables.data ?? variables) : variables;
-                const cfg = consistency?.familySync ?? DEFAULT_FAMILY_SYNC;
-                syncEntityAcrossFamily(queryClient, familyKey, cfg, op, payload);
-            }
+            // Determine invalidation scope
             const scope = optimistic.invalidateScope ?? (isListFamilyKey(optimistic.queryKey) ? "family" : "exact");
             const invalidations = [];
-            if (invalidate) {
-                if (scope !== "none") {
-                    if (scope === "family") {
-                        const familyKey = optimistic.familyKey ?? deriveFamilyKey(optimistic.queryKey);
-                        invalidations.push({ queryKey: familyKey });
-                    }
-                    else {
-                        invalidations.push({ queryKey: optimistic.queryKey });
-                    }
-                }
-                if (Array.isArray(optimistic.relatedKeys) && optimistic.relatedKeys.length > 0) {
-                    optimistic.relatedKeys.forEach((k) => invalidations.push({ queryKey: k }));
+            if (scope !== "none") {
+                if (scope === "family") {
+                    const familyKey = optimistic.familyKey ?? deriveFamilyKey(optimistic.queryKey);
+                    invalidations.push({ queryKey: familyKey });
                 }
-                if (Array.isArray(optimistic.invalidates) && optimistic.invalidates.length > 0) {
-                    optimistic.invalidates.forEach((k) => invalidations.push({ queryKey: k }));
+                else {
+                    invalidations.push({ queryKey: optimistic.queryKey });
                 }
             }
+            // Add related keys
+            if (Array.isArray(optimistic.relatedKeys) && optimistic.relatedKeys.length > 0) {
+                optimistic.relatedKeys.forEach((k) => invalidations.push({ queryKey: k }));
+            }
+            if (Array.isArray(optimistic.invalidates) && optimistic.invalidates.length > 0) {
+                optimistic.invalidates.forEach((k) => invalidations.push({ queryKey: k }));
+            }
+            // Execute invalidations (deduplicated)
             if (invalidations.length > 0) {
                 const seen = new Set();
                 const tasks = invalidations
@@ -177,13 +146,7 @@ export function useMutation(options) {
                     seen.add(key);
                     return true;
                 });
-                const delay = consistency?.invalidationDelay ?? (consistency?.mode === "auto" ? 1000 : 0);
-                if (delay > 0) {
-                    setTimeout(() => executeInvalidations(queryClient, tasks), delay);
-                }
-                else {
-                    executeInvalidations(queryClient, tasks);
-                }
+                tasks.forEach(task => queryClient.invalidateQueries(task));
             }
             if (onSuccess) {
                 const successCallback = onSuccess;
@@ -206,28 +169,10 @@ export function useListMutation(mutationFn, queryKey, options) {
     const queryClient = useQueryClient();
     return useTanStackMutation({
         mutationFn,
-        onSuccess: (_data, variables) => {
-            const { sync } = getConsistencyStrategy(options?.consistency?.mode, variables.operation);
-            if (sync) {
-                const familyKey = deriveFamilyKey(queryKey);
-                const cfg = options?.consistency?.familySync ?? DEFAULT_FAMILY_SYNC;
-                syncEntityAcrossFamily(queryClient, familyKey, cfg, variables.operation, variables.data);
-            }
-        },
-        onSettled: (data, error, variables) => {
-            const { invalidate } = getConsistencyStrategy(options?.consistency?.mode, variables.operation);
-            if (invalidate) {
-                const familyKey = deriveFamilyKey(queryKey);
-                const delay = options?.consistency?.invalidationDelay ?? (options?.consistency?.mode === "auto" ? 1000 : 0);
-                if (delay > 0) {
-                    setTimeout(() => {
-                        queryClient.invalidateQueries({ queryKey: familyKey, exact: false });
-                    }, delay);
-                }
-                else {
-                    queryClient.invalidateQueries({ queryKey: familyKey, exact: false });
-                }
-            }
+        onSettled: () => {
+            // Invalidate all queries in the family
+            const familyKey = deriveFamilyKey(queryKey);
+            queryClient.invalidateQueries({ queryKey: familyKey, exact: false });
         },
         ...options,
         mutationKey: options?.mutationKey

package/dist/types/index.d.ts

@@ -8,56 +8,46 @@ export * from "./persistence.js";
 export * from "./selectors.js";
 export * from "./suspense.js";
 export interface MutationContext<TData = unknown, TContext = unknown> {
-    previousData?: TData;
+    /** Snapshots of all query variants (from getQueriesData) */
+    previousData?: Array<[QueryKey, any]>;
+    /** User-provided context from onMutate */
     userContext?: TContext;
+    /** For conditional mutations */
     conditionMet?: boolean;
-    familyRollbackData?: Array<{
-        queryKey: QueryKey;
-        previousData: unknown;
-    }>;
 }
+/**
+ * Enhanced mutation options using official TanStack Query approach
+ *
+ * Uses setQueriesData to update all cached query variants automatically.
+ * This prevents data rollback and flicker when switching between pageSize, filters, etc.
+ *
+ * Recommended: Use long staleTime (5+ minutes) in your queries for best results.
+ */
 export interface MutationOptions<TData, TError, TVariables, TContext = unknown> extends UseMutationOptions<TData, TError, TVariables, TContext> {
     optimistic?: {
+        /** Query key to update (will also update all variants in the same family) */
         queryKey: QueryKey;
+        /** Function to update the cached data - will be applied to all query variants */
         updater: <TQueryData = unknown>(oldData: TQueryData | undefined, variables: TVariables) => TQueryData | undefined;
+        /** Enable/disable optimistic updates */
         enabled?: boolean;
+        /** Map mutation variable fields to cache data fields */
         fieldMapping?: Record<string, string>;
+        /** Callback when rollback occurs on error */
         rollback?: <TQueryData = unknown>(previousData: TQueryData, error: Error) => void;
+        /**
+         * Invalidation scope after success:
+         * - "exact": Only invalidate the exact queryKey
+         * - "family": Invalidate all queries in the family (default for list queries)
+         * - "none": Don't invalidate (rely on optimistic update only)
+         */
         invalidateScope?: "none" | "exact" | "family";
+        /** Override the derived family key (e.g., ['products', 'list']) */
         familyKey?: QueryKey;
+        /** Additional query keys to invalidate */
         relatedKeys?: QueryKey[];
+        /** Alias for relatedKeys */
         invalidates?: QueryKey[];
     };
-    consistency?: {
-        familySync?: {
-            idField?: string;
-            listSelector?: (data: unknown) => {
-                items: unknown[];
-                total?: number;
-            } | null;
-            writeBack?: (old: unknown, items: unknown[], total?: number) => unknown;
-            maxKeys?: number;
-            enableForOperations?: Array<"update" | "delete">;
-        };
-        /**
-         * Consistency strategy:
-         * - "sync+invalidate": Update cache locally AND invalidate queries (default).
-         * - "sync-only": Update cache locally only (use when server is eventually consistent and you trust the client).
-         * - "invalidate-only": Do not update cache locally, just invalidate.
-         * - "auto": "sync-only" for updates, "sync+invalidate" for deletes.
-         */
-        mode?: "sync+invalidate" | "invalidate-only" | "sync-only" | "auto";
-        /**
-         * Default operation type if not provided in variables.
-         * Useful for useMutation where variables might not contain operation info.
-         */
-        defaultOperation?: "create" | "update" | "delete";
-        /**
-         * Delay in milliseconds before invalidating queries.
-         * Useful for eventually consistent backends (e.g. ElasticSearch).
-         * Default: 0
-         */
-        invalidationDelay?: number;
-    };
 }
 //# 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,gBAAgB,CAAC;AAC/B,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,CAAC;IAAC,kBAAkB,CAAC,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,QAAQ,CAAC;QAAC,YAAY,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAAE;AAC1N,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;QACX,QAAQ,EAAE,QAAQ,CAAC;QACnB,OAAO,EAAE,CAAC,UAAU,GAAG,OAAO,EAAE,OAAO,EAAE,UAAU,GAAG,SAAS,EAAE,SAAS,EAAE,UAAU,KAAK,UAAU,GAAG,SAAS,CAAC;QAClH,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACtC,QAAQ,CAAC,EAAE,CAAC,UAAU,GAAG,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;QAClF,eAAe,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;QAC9C,SAAS,CAAC,EAAE,QAAQ,CAAC;QACrB,WAAW,CAAC,EAAE,QAAQ,EAAE,CAAC;QACzB,WAAW,CAAC,EAAE,QAAQ,EAAE,CAAC;KAC1B,CAAC;IACF,WAAW,CAAC,EAAE;QACZ,UAAU,CAAC,EAAE;YACX,OAAO,CAAC,EAAE,MAAM,CAAC;YACjB,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK;gBAAE,KAAK,EAAE,OAAO,EAAE,CAAC;gBAAC,KAAK,CAAC,EAAE,MAAM,CAAA;aAAE,GAAG,IAAI,CAAC;YAC9E,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;YACxE,OAAO,CAAC,EAAE,MAAM,CAAC;YACjB,mBAAmB,CAAC,EAAE,KAAK,CAAC,QAAQ,GAAG,QAAQ,CAAC,CAAC;SAClD,CAAC;QACF;;;;;;WAMG;QACH,IAAI,CAAC,EAAE,iBAAiB,GAAG,iBAAiB,GAAG,WAAW,GAAG,MAAM,CAAC;QACpE;;;WAGG;QACH,gBAAgB,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;QAClD;;;;WAIG;QACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;KAC5B,CAAC;CACH"}
+{"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,gBAAgB,CAAC;AAC/B,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;IAClE,4DAA4D;IAC5D,YAAY,CAAC,EAAE,KAAK,CAAC,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC;IACtC,0CAA0C;IAC1C,WAAW,CAAC,EAAE,QAAQ,CAAC;IACvB,gCAAgC;IAChC,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AACD;;;;;;;GAOG;AACH,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;QACX,6EAA6E;QAC7E,QAAQ,EAAE,QAAQ,CAAC;QACnB,iFAAiF;QACjF,OAAO,EAAE,CAAC,UAAU,GAAG,OAAO,EAAE,OAAO,EAAE,UAAU,GAAG,SAAS,EAAE,SAAS,EAAE,UAAU,KAAK,UAAU,GAAG,SAAS,CAAC;QAClH,wCAAwC;QACxC,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,wDAAwD;QACxD,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACtC,6CAA6C;QAC7C,QAAQ,CAAC,EAAE,CAAC,UAAU,GAAG,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;QAClF;;;;;WAKG;QACH,eAAe,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;QAC9C,mEAAmE;QACnE,SAAS,CAAC,EAAE,QAAQ,CAAC;QACrB,0CAA0C;QAC1C,WAAW,CAAC,EAAE,QAAQ,EAAE,CAAC;QACzB,4BAA4B;QAC5B,WAAW,CAAC,EAAE,QAAQ,EAAE,CAAC;KAC1B,CAAC;CACH"}

package/dist/utils/dataGuard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dataGuard.d.ts","sourceRoot":"","sources":["../../src/utils/dataGuard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,0BAA0B,EAC3B,MAAM,uBAAuB,CAAC;AA+B/B;;GAEG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAO3C;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,eAAe,EACtD,OAAO,EAAE,0BAA0B,CAAC,CAAC,CAAC,EACtC,MAAM,EAAE,0BAA0B,CAAC,CAAC,CAAC,GAAG,SAAS,EACjD,QAAQ,EAAE,QAAQ,EAClB,OAAO,GAAE,gBAAqB,GAC7B;IACD,YAAY,EAAE,OAAO,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,YAAY,EAAE,GAAG,CAAC;CACnB,CA+IA;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,eAAe,EACrD,IAAI,EAAE,0BAA0B,CAAC,CAAC,CAAC,GAClC,0BAA0B,CAAC,CAAC,CAAC,CAK/B;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,eAAe,EAC3D,IAAI,EAAE,0BAA0B,CAAC,CAAC,CAAC,EACnC,SAAS,EAAE,MAAM,GAAG,MAAM,GACzB,0BAA0B,CAAC,CAAC,CAAC,CAQ/B;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,eAAe,EAC5D,IAAI,EAAE,0BAA0B,CAAC,CAAC,CAAC,EACnC,SAAS,EAAE,MAAM,GAAG,MAAM,GACzB,0BAA0B,CAAC,CAAC,CAAC,CAU/B;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,eAAe,EAC5D,WAAW,EAAE,WAAW,EACxB,SAAS,EAAE,QAAQ,EACnB,QAAQ,EAAE,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,GAC/C,IAAI,CAiCN"}
+{"version":3,"file":"dataGuard.d.ts","sourceRoot":"","sources":["../../src/utils/dataGuard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,0BAA0B,EAC3B,MAAM,uBAAuB,CAAC;AA+C/B;;GAEG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAO3C;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,eAAe,EACtD,OAAO,EAAE,0BAA0B,CAAC,CAAC,CAAC,EACtC,MAAM,EAAE,0BAA0B,CAAC,CAAC,CAAC,GAAG,SAAS,EACjD,QAAQ,EAAE,QAAQ,EAClB,OAAO,GAAE,gBAAqB,GAC7B;IACD,YAAY,EAAE,OAAO,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,YAAY,EAAE,GAAG,CAAC;CACnB,CA+IA;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,eAAe,EACrD,IAAI,EAAE,0BAA0B,CAAC,CAAC,CAAC,GAClC,0BAA0B,CAAC,CAAC,CAAC,CAK/B;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,eAAe,EAC3D,IAAI,EAAE,0BAA0B,CAAC,CAAC,CAAC,EACnC,SAAS,EAAE,MAAM,GAAG,MAAM,GACzB,0BAA0B,CAAC,CAAC,CAAC,CAQ/B;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,eAAe,EAC5D,IAAI,EAAE,0BAA0B,CAAC,CAAC,CAAC,EACnC,SAAS,EAAE,MAAM,GAAG,MAAM,GACzB,0BAA0B,CAAC,CAAC,CAAC,CAU/B;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,eAAe,EAC5D,WAAW,EAAE,WAAW,EACxB,SAAS,EAAE,QAAQ,EACnB,QAAQ,EAAE,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,GAC/C,IAAI,CAiCN"}

package/dist/utils/dataGuard.js

@@ -1,4 +1,18 @@
-import { startsWithKeyPrefix } from "./consistency.js";
+/**
+ * Check if a query key starts with a given prefix
+ */
+function startsWithKeyPrefix(key, prefix) {
+    const k = Array.isArray(key) ? key : [key];
+    const p = Array.isArray(prefix) ? prefix : [prefix];
+    if (p.length > k.length)
+        return false;
+    for (let i = 0; i < p.length; i++) {
+        if (JSON.stringify(k[i]) !== JSON.stringify(p[i])) {
+            return false;
+        }
+    }
+    return true;
+}
 /**
  * 简单的字符串哈希函数（DJB2算法变体）
  */

package/dist/utils/index.d.ts

@@ -6,6 +6,5 @@ export { getPrefetchManager, type InteractionRecord, type NetworkSpeed, type Pre
 export { createQueryKeyFactory, createSimpleQueryKeyFactory, extractParamsFromKey, isQueryKeyEqual, type NormalizeConfig, normalizeQueryParams, type QueryKeyFactory, type QueryKeyFactoryConfig } from "./queryKey.js";
 export { compose, selectById, selectByIds, selectCount, selectField, selectFields, selectFirst, selectItems, selectLast, selectMap, selectors, selectTotal, selectWhere } from "./selectors.js";
 export { deepClone, formatBytes, getStorageUsage, isStorageAvailable } from "./storage.js";
-export { startsWithKeyPrefix, syncEntityAcrossFamily, DEFAULT_FAMILY_SYNC, type FamilySyncConfig } from "./consistency.js";
 export { applyDataGuard, addHashToData, hashObject, markRecentlyUpdated, clearRecentlyUpdated, updateFamilyMetadata } from "./dataGuard.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,YAAY,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACpH,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,aAAa,EAAE,aAAa,EAAE,KAAK,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAC3H,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,KAAK,sBAAsB,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAC1P,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC/E,OAAO,EAAE,kBAAkB,EAAE,KAAK,iBAAiB,EAAE,KAAK,YAAY,EAAE,KAAK,gBAAgB,EAAE,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACpO,OAAO,EAAE,qBAAqB,EAAE,2BAA2B,EAAE,oBAAoB,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,oBAAoB,EAAE,KAAK,eAAe,EAAE,KAAK,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACxN,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAChM,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAC3F,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAC3H,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,UAAU,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,YAAY,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACpH,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,aAAa,EAAE,aAAa,EAAE,KAAK,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAC3H,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,KAAK,sBAAsB,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAC1P,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC/E,OAAO,EAAE,kBAAkB,EAAE,KAAK,iBAAiB,EAAE,KAAK,YAAY,EAAE,KAAK,gBAAgB,EAAE,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACpO,OAAO,EAAE,qBAAqB,EAAE,2BAA2B,EAAE,oBAAoB,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,oBAAoB,EAAE,KAAK,eAAe,EAAE,KAAK,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACxN,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAChM,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAC3F,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,UAAU,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/utils/index.js

@@ -6,5 +6,4 @@ export { getPrefetchManager, resetPrefetchManager, SmartPrefetchManager } from "
 export { createQueryKeyFactory, createSimpleQueryKeyFactory, extractParamsFromKey, isQueryKeyEqual, normalizeQueryParams } from "./queryKey.js";
 export { compose, selectById, selectByIds, selectCount, selectField, selectFields, selectFirst, selectItems, selectLast, selectMap, selectors, selectTotal, selectWhere } from "./selectors.js";
 export { deepClone, formatBytes, getStorageUsage, isStorageAvailable } from "./storage.js";
-export { startsWithKeyPrefix, syncEntityAcrossFamily, DEFAULT_FAMILY_SYNC } from "./consistency.js";
 export { applyDataGuard, addHashToData, hashObject, markRecentlyUpdated, clearRecentlyUpdated, updateFamilyMetadata } from "./dataGuard.js";

package/package.json

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

package/dist/utils/consistency.d.ts

@@ -1,25 +0,0 @@
-import type { QueryClient, QueryKey } from "@tanstack/react-query";
-import type { EntityWithId } from "../types/selectors";
-export declare function startsWithKeyPrefix(key: QueryKey, prefix: QueryKey): boolean;
-export type FamilySyncConfig = {
-    idField?: string;
-    listSelector?: (data: unknown) => {
-        items: EntityWithId[];
-        total?: number;
-    } | null;
-    writeBack?: (old: unknown, items: EntityWithId[], total?: number) => unknown;
-    maxKeys?: number;
-    enableForOperations?: Array<"update" | "delete">;
-};
-export declare function defaultListSelector(data: unknown): {
-    items: EntityWithId[];
-    total?: number;
-} | null;
-export declare function defaultWriteBack(old: unknown, items: EntityWithId[], total?: number): unknown;
-export declare const DEFAULT_FAMILY_SYNC: FamilySyncConfig;
-export declare function syncEntityAcrossFamily(queryClient: QueryClient, familyPrefix: QueryKey, cfg: FamilySyncConfig, operation: string, payload: Partial<EntityWithId>): void;
-export declare function syncEntityAcrossFamilyOptimistic(queryClient: QueryClient, familyPrefix: QueryKey, cfg: FamilySyncConfig, operation: string, payload: Partial<EntityWithId>): Array<{
-    queryKey: QueryKey;
-    previousData: unknown;
-}>;
-//# sourceMappingURL=consistency.d.ts.map

package/dist/utils/consistency.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"consistency.d.ts","sourceRoot":"","sources":["../../src/utils/consistency.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAwCvD,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,GAAG,OAAO,CAgB5E;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK;QAAE,KAAK,EAAE,YAAY,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACnF,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mBAAmB,CAAC,EAAE,KAAK,CAAC,QAAQ,GAAG,QAAQ,CAAC,CAAC;CAClD,CAAC;AAEF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG;IAAE,KAAK,EAAE,YAAY,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAiBnG;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAe7F;AAED,eAAO,MAAM,mBAAmB,EAAE,gBAMjC,CAAC;AAEF,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,WAAW,EACxB,YAAY,EAAE,QAAQ,EACtB,GAAG,EAAE,gBAAgB,EACrB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,OAAO,CAAC,YAAY,CAAC,GAC7B,IAAI,CAuCN;AAED,wBAAgB,gCAAgC,CAC9C,WAAW,EAAE,WAAW,EACxB,YAAY,EAAE,QAAQ,EACtB,GAAG,EAAE,gBAAgB,EACrB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,OAAO,CAAC,YAAY,CAAC,GAC7B,KAAK,CAAC;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,YAAY,EAAE,OAAO,CAAA;CAAE,CAAC,CAoDtD"}

package/dist/utils/consistency.js

@@ -1,183 +0,0 @@
-import { listUpdater, idsAreEqual } from "./optimisticUtils.js";
-function ensureArray(key) {
-    return Array.isArray(key) ? key : [key];
-}
-/**
- * Robust deep equality check that handles object key order and common types
- */
-function deepEqual(a, b) {
-    if (a === b)
-        return true;
-    if (a && b && typeof a === "object" && typeof b === "object") {
-        if (Array.isArray(a)) {
-            if (!Array.isArray(b) || a.length !== b.length)
-                return false;
-            for (let i = 0; i < a.length; i++) {
-                if (!deepEqual(a[i], b[i]))
-                    return false;
-            }
-            return true;
-        }
-        // Handle plain objects
-        const keysA = Object.keys(a);
-        const keysB = Object.keys(b);
-        if (keysA.length !== keysB.length)
-            return false;
-        // Check if all keys in A exist in B and values are deep equal
-        // Key order doesn't matter here because we look up by key
-        for (const key of keysA) {
-            if (!Object.prototype.hasOwnProperty.call(b, key))
-                return false;
-            if (!deepEqual(a[key], b[key]))
-                return false;
-        }
-        return true;
-    }
-    return false;
-}
-export function startsWithKeyPrefix(key, prefix) {
-    const k = ensureArray(key);
-    const p = ensureArray(prefix);
-    if (p.length > k.length)
-        return false;
-    for (let i = 0; i < p.length; i++) {
-        const a = k[i];
-        const b = p[i];
-        // Check for equality using robust deepEqual
-        if (!deepEqual(a, b)) {
-            return false;
-        }
-    }
-    return true;
-}
-export function defaultListSelector(data) {
-    if (!data)
-        return null;
-    if (Array.isArray(data))
-        return { items: data };
-    if (typeof data === "object") {
-        const obj = data;
-        if (Array.isArray(obj.items))
-            return {
-                items: obj.items,
-                total: typeof obj.total === "number" ? obj.total : undefined
-            };
-        if (Array.isArray(obj.Rows))
-            return {
-                items: obj.Rows,
-                total: typeof obj.Total === "number" ? obj.Total : undefined
-            };
-    }
-    return null;
-}
-export function defaultWriteBack(old, items, total) {
-    if (old && typeof old === "object") {
-        const obj = { ...old };
-        if (Array.isArray(obj.Rows)) {
-            obj.Rows = items;
-            if (typeof total !== "undefined")
-                obj.Total = total;
-            return obj;
-        }
-        if (Array.isArray(obj.items)) {
-            obj.items = items;
-            if (typeof total !== "undefined")
-                obj.total = total;
-            return obj;
-        }
-    }
-    return { items, total };
-}
-export const DEFAULT_FAMILY_SYNC = {
-    idField: "id",
-    listSelector: defaultListSelector,
-    writeBack: defaultWriteBack,
-    maxKeys: 50,
-    enableForOperations: ["update", "delete"]
-};
-export function syncEntityAcrossFamily(queryClient, familyPrefix, cfg, operation, payload) {
-    const enabledOps = cfg.enableForOperations ?? ["update", "delete"];
-    const op = String(operation).toLowerCase();
-    if (!enabledOps.includes(op))
-        return;
-    const idField = cfg.idField ?? "id";
-    const cache = queryClient.getQueryCache();
-    const queries = cache.findAll({ predicate: (q) => startsWithKeyPrefix(q.queryKey, familyPrefix) });
-    const limited = typeof cfg.maxKeys === "number" && cfg.maxKeys > 0 ? queries.slice(0, cfg.maxKeys) : queries;
-    limited.forEach((q) => {
-        const key = q.queryKey;
-        const old = queryClient.getQueryData(key);
-        const picked = (cfg.listSelector ?? defaultListSelector)(old);
-        if (!picked || !Array.isArray(picked.items))
-            return;
-        const idValue = (typeof payload === "string" || typeof payload === "number") ? payload : payload?.[idField];
-        let items = picked.items;
-        if (op === "update" && idValue !== undefined) {
-            const existingItem = items.find(item => idsAreEqual(item[idField], idValue));
-            if (existingItem) {
-                const strictId = existingItem[idField];
-                if (typeof payload === "object") {
-                    items = listUpdater.update(items, { ...payload, [idField]: strictId });
-                }
-            }
-        }
-        else if (op === "delete" && idValue !== undefined) {
-            const existingItem = items.find(item => idsAreEqual(item[idField], idValue));
-            if (existingItem) {
-                const strictId = existingItem[idField];
-                items = listUpdater.remove(items, strictId);
-            }
-        }
-        const total = typeof picked.total === "number" && op === "delete" ? Math.max(0, picked.total - 1) : picked.total;
-        const next = (cfg.writeBack ?? defaultWriteBack)(old, items, total);
-        queryClient.setQueryData(key, next);
-    });
-}
-export function syncEntityAcrossFamilyOptimistic(queryClient, familyPrefix, cfg, operation, payload) {
-    const rollbackData = [];
-    const enabledOps = cfg.enableForOperations ?? ["update", "delete"];
-    const op = String(operation).toLowerCase();
-    if (!enabledOps.includes(op))
-        return rollbackData;
-    const idField = cfg.idField ?? "id";
-    const cache = queryClient.getQueryCache();
-    const queries = cache.findAll({ predicate: (q) => startsWithKeyPrefix(q.queryKey, familyPrefix) });
-    const limited = typeof cfg.maxKeys === "number" && cfg.maxKeys > 0 ? queries.slice(0, cfg.maxKeys) : queries;
-    limited.forEach((q) => {
-        const key = q.queryKey;
-        const old = queryClient.getQueryData(key);
-        const picked = (cfg.listSelector ?? defaultListSelector)(old);
-        if (!picked || !Array.isArray(picked.items))
-            return;
-        const idValue = (typeof payload === "string" || typeof payload === "number") ? payload : payload?.[idField];
-        let items = picked.items;
-        let shouldUpdate = false;
-        if (op === "update" && idValue !== undefined) {
-            // Robust ID check
-            const existingItem = items.find(item => idsAreEqual(item[idField], idValue));
-            if (existingItem) {
-                const strictId = existingItem[idField];
-                // Ensure payload uses the correct ID type from the store
-                if (typeof payload === "object") {
-                    items = listUpdater.update(items, { ...payload, [idField]: strictId });
-                    shouldUpdate = true;
-                }
-            }
-        }
-        else if (op === "delete" && idValue !== undefined) {
-            const existingItem = items.find(item => idsAreEqual(item[idField], idValue));
-            if (existingItem) {
-                const strictId = existingItem[idField];
-                items = listUpdater.remove(items, strictId);
-                shouldUpdate = true;
-            }
-        }
-        if (shouldUpdate) {
-            rollbackData.push({ queryKey: key, previousData: old });
-            const total = typeof picked.total === "number" && op === "delete" ? Math.max(0, picked.total - 1) : picked.total;
-            const next = (cfg.writeBack ?? defaultWriteBack)(old, items, total);
-            queryClient.setQueryData(key, next);
-        }
-    });
-    return rollbackData;
-}