@qiaopeng/tanstack-query-plus 0.2.3 → 0.2.5

package/README.md

@@ -968,7 +968,7 @@ const list7 = conditionalUpdateItems(
 )
 ```
 
-### 7.9 完整示例：Todo 应用
+ ### 7.9 完整示例：Todo 应用
 
 ```tsx
 import { useEnhancedQuery, useMutation } from '@qiaopeng/tanstack-query-plus/hooks'
@@ -1038,54 +1038,55 @@ function TodoApp() {
       </ul>
     </div>
   )
+  }
 }
 ```
 
-### 7.10 跨分页一致性：前缀失效与缓存对齐
+### 7.10 分页家族一致性（避免分页切换回退）
 
-在分页列表中，乐观更新通常只更新“当前页”的缓存。为了保证切换到其他页时也看到最新数据，可以使用前缀级失效与跨页缓存对齐：
+在带分页/筛选/排序的列表中，编辑、新增、删除、状态变更成功后切换 `page/pageSize` 时，可能命中同一资源的另一查询变体，从而短暂显示旧快照。本库提供可选的“家族一致性”能力，保障在成功后切换分页不回退。
 
-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 的乐观更新中启用跨页对齐与前缀失效：
+- 开启方式：在 `useMutation` 传入 `consistency` 配置（默认关闭，显式启用）
+- 安全默认：`mode: 'invalidate'` 只执行家族失效，确保最终与服务端一致
+- 进阶模式：`mode: 'sync+invalidate'` 先对缓存中已存在的变体按 `id` 合并更新，再统一失效
+- 形状适配：通过 `listSelector` 适配 `{items,total}` 结构；无法识别时自动降级为仅失效
 
 ```tsx
 import { useMutation } from '@qiaopeng/tanstack-query-plus/hooks'
+import { createPaginatedKey } from '@qiaopeng/tanstack-query-plus/core'
 
-function UpdateProduct({ product }) {
-  const mutation = useMutation({
-    mutationFn: (patch) => api.updateProduct(product.id, patch),
+function useUpdateProduct({ page, pageSize }) {
+  return useMutation({
+    mutationFn: (updated) => api.updateProduct(updated.id, updated),
+
+    // 当前页的乐观更新：先更新 UI，再发请求，失败自动回滚
     optimistic: {
-      queryKey: productKeys.detail(product.id),
-      updater: (oldData, patch) => ({ ...oldData, ...patch }),
-      invalidateScope: 'prefix',
-      invalidatePrefixKey: listPrefix,
-      reconcileCachedPages: true
-    }
-  })
+      queryKey: createPaginatedKey(['products', 'list'], page, pageSize),
+      updater: (old, updated) => old?.map((p) => (p.id === updated.id ? { ...p, ...updated } : p)),
+    },
 
-  return (
-    <button onClick={() => mutation.mutate({ title: '新标题' })}>
-      更新商品
-    </button>
-  )
+    // 家族一致性：编辑成功后，保障跨分页/筛选/排序的变体不回退
+    consistency: {
+      baseKey: ['products', 'list'],
+      mode: 'sync+invalidate',
+      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,
+    },
+  })
 }
 ```
 
-行为说明：
-- 乐观阶段：先更新当前 key，对已缓存的所有分页列表也应用同样的更新，使切页立即看到新值。
-- 成功后：对域前缀进行失效，后续展示从服务端获取最终一致数据。
-
-注意事项：
-- 请确保分页查询的 Key 都共享同一前缀（例如通过 `createDomainKeyFactory`），否则前缀失效无法覆盖所有分页。
-- 在超大列表场景中，跨页对齐可能带来一定开销，可按需开启。
+适用操作与行为说明：
+- 编辑/删除：在 `sync+invalidate` 模式下，会对已缓存的家族变体按 `id` 合并或移除；随后统一失效，最终以服务端为准
+- 新增/状态变更：默认不做跨页注入，仅当前页处理并家族失效；需要跨页放置时请在服务端裁决归属
 
 现在你已经掌握了数据变更和乐观更新。接下来，让我们学习如何处理无限滚动和分页场景。
 
@@ -3245,6 +3246,36 @@ function SearchResults({ query }) {
 }
 ```
 
+### 14.11 家族一致性工具
+
+在某些高级场景下，你可能需要自行枚举并同步同一资源的家族查询变体（分页/筛选/排序等）。本库提供了工具函数用于匹配与安全同步：
+
+```tsx
+import { useQueryClient } from '@qiaopeng/tanstack-query-plus'
+import { findFamilyQueries, syncEntityAcrossFamily } from '@qiaopeng/tanstack-query-plus/utils'
+
+function useManualFamilySync() {
+  const queryClient = useQueryClient()
+  const sync = (updated) => {
+    const keys = findFamilyQueries(queryClient, { baseKey: ['products', 'list'], maxKeys: 50 })
+    syncEntityAcrossFamily(queryClient, keys, updated, {
+      idField: 'id',
+      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
+      },
+    })
+    keys.forEach((key) => queryClient.invalidateQueries({ queryKey: key }))
+  }
+  return { sync }
+}
+```
+
+提示：上述工具已在 `useMutation` 的一致性配置中自动使用；仅在需要手动控制时使用它们。
+
 现在你已经掌握了所有核心功能！最后，让我们看看一些最佳实践和常见问题。
 
 ---

package/dist/core/index.d.ts

@@ -5,4 +5,5 @@ export { isDev, isProd, isTest } from "./env.js";
 export { focusManager, type FocusManagerConfig, getSmartFocusManager, pauseFocusManager, resetSmartFocusManager, resumeFocusManager, setupFocusManager, SmartFocusManager } from "./focusManager.js";
 export { areKeysEqual, containsEntity, createComplexKey, createDomainKeyFactory, createFilteredKey, createMutationKeyFactory, createPaginatedKey, createSearchKey, createSortedKey, extractEntityId, matchesKeyPattern, normalizeQueryKey, queryKeys, validateQueryKey } from "./keys.js";
 export { createAppQueryOptions, createAppQueryOptionsWithSelect } from "./queryOptions.js";
+export { createListQueryOptions, type ListQueryConfig } from "./queryOptions.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,uBAAuB,EACvB,oBAAoB,EACpB,kBAAkB,EAClB,4BAA4B,EAC5B,yBAAyB,EACzB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,sBAAsB,EACtB,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,2BAA2B,EAC3B,cAAc,EACd,cAAc,EACd,cAAc,EACf,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,KAAK,cAAc,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACpH,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,EACL,YAAY,EACZ,KAAK,kBAAkB,EACvB,oBAAoB,EACpB,iBAAiB,EACjB,sBAAsB,EACtB,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,sBAAsB,EACtB,iBAAiB,EACjB,wBAAwB,EACxB,kBAAkB,EAClB,eAAe,EACf,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,SAAS,EACT,gBAAgB,EACjB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,qBAAqB,EAAE,+BAA+B,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,uBAAuB,EACvB,oBAAoB,EACpB,kBAAkB,EAClB,4BAA4B,EAC5B,yBAAyB,EACzB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,sBAAsB,EACtB,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,2BAA2B,EAC3B,cAAc,EACd,cAAc,EACd,cAAc,EACf,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,KAAK,cAAc,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACpH,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,EACL,YAAY,EACZ,KAAK,kBAAkB,EACvB,oBAAoB,EACpB,iBAAiB,EACjB,sBAAsB,EACtB,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,sBAAsB,EACtB,iBAAiB,EACjB,wBAAwB,EACxB,kBAAkB,EAClB,eAAe,EACf,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,SAAS,EACT,gBAAgB,EACjB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,qBAAqB,EAAE,+BAA+B,EAAE,MAAM,mBAAmB,CAAC;AAC3F,OAAO,EAAE,sBAAsB,EAAE,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/core/index.js

@@ -5,3 +5,4 @@ export { isDev, isProd, isTest } from "./env.js";
 export { focusManager, getSmartFocusManager, pauseFocusManager, resetSmartFocusManager, resumeFocusManager, setupFocusManager, SmartFocusManager } from "./focusManager.js";
 export { areKeysEqual, containsEntity, createComplexKey, createDomainKeyFactory, createFilteredKey, createMutationKeyFactory, createPaginatedKey, createSearchKey, createSortedKey, extractEntityId, matchesKeyPattern, normalizeQueryKey, queryKeys, validateQueryKey } from "./keys.js";
 export { createAppQueryOptions, createAppQueryOptionsWithSelect } from "./queryOptions.js";
+export { createListQueryOptions } from "./queryOptions.js";

package/dist/core/queryOptions.d.ts

@@ -11,4 +11,9 @@ export interface SelectQueryConfig<TData, TSelected = TData> extends Omit<BaseQu
     select: (data: TData) => TSelected;
 }
 export declare function createAppQueryOptionsWithSelect<TData, TSelected = TData>(config: SelectQueryConfig<TData, TSelected>): UseQueryOptions<TData, DefaultError, TSelected, QueryKey>;
+export interface ListQueryConfig<TData> extends Omit<BaseQueryConfig<TData>, "staleTime" | "gcTime"> {
+    staleTime?: number;
+    gcTime?: number;
+}
+export declare function createListQueryOptions<TData>(config: ListQueryConfig<TData>): UseQueryOptions<TData, DefaultError, TData, QueryKey>;
 //# sourceMappingURL=queryOptions.d.ts.map

package/dist/core/queryOptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"queryOptions.d.ts","sourceRoot":"","sources":["../../src/core/queryOptions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAIpG,MAAM,WAAW,eAAe,CAAC,KAAK;IACpC,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,EAAE,aAAa,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,eAAe,CAAC,KAAK,CAAC,GAAG,eAAe,CAAC,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,QAAQ,CAAC,CAalI;AAED,MAAM,WAAW,iBAAiB,CAAC,KAAK,EAAE,SAAS,GAAG,KAAK,CAAE,SAAQ,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;IAC1G,MAAM,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,SAAS,CAAC;CACpC;AAED,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,SAAS,GAAG,KAAK,EAAE,MAAM,EAAE,iBAAiB,CAAC,KAAK,EAAE,SAAS,CAAC,GAAG,eAAe,CAAC,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,QAAQ,CAAC,CAahL"}
+{"version":3,"file":"queryOptions.d.ts","sourceRoot":"","sources":["../../src/core/queryOptions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAIpG,MAAM,WAAW,eAAe,CAAC,KAAK;IACpC,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,EAAE,aAAa,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,eAAe,CAAC,KAAK,CAAC,GAAG,eAAe,CAAC,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,QAAQ,CAAC,CAalI;AAED,MAAM,WAAW,iBAAiB,CAAC,KAAK,EAAE,SAAS,GAAG,KAAK,CAAE,SAAQ,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;IAC1G,MAAM,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,SAAS,CAAC;CACpC;AAED,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,SAAS,GAAG,KAAK,EAAE,MAAM,EAAE,iBAAiB,CAAC,KAAK,EAAE,SAAS,CAAC,GAAG,eAAe,CAAC,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,QAAQ,CAAC,CAahL;AAED,MAAM,WAAW,eAAe,CAAC,KAAK,CAAE,SAAQ,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,WAAW,GAAG,QAAQ,CAAC;IAClG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,eAAe,CAAC,KAAK,CAAC,GAAG,eAAe,CAAC,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,QAAQ,CAAC,CAanI"}

package/dist/core/queryOptions.js

@@ -28,3 +28,17 @@ export function createAppQueryOptionsWithSelect(config) {
         refetchOnMount: true
     });
 }
+export function createListQueryOptions(config) {
+    return queryOptions({
+        queryKey: config.queryKey,
+        queryFn: config.queryFn,
+        staleTime: config.staleTime ?? 0,
+        gcTime: config.gcTime ?? DEFAULT_GC_TIME,
+        enabled: config.enabled,
+        retry: defaultQueryRetryStrategy,
+        retryDelay: exponentialBackoff,
+        refetchOnWindowFocus: true,
+        refetchOnReconnect: true,
+        refetchOnMount: true
+    });
+}

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

@@ -1,5 +1,25 @@
 import { useQueryClient, useMutation as useTanStackMutation } from "@tanstack/react-query";
 import { DEFAULT_MUTATION_CONFIG } from "../core/config.js";
+function deriveFamilyKey(queryKey) {
+    const arr = Array.isArray(queryKey) ? [...queryKey] : [queryKey];
+    while (arr.length > 1) {
+        const last = arr[arr.length - 1];
+        if (last && typeof last === "object" && !Array.isArray(last)) {
+            arr.pop();
+            continue;
+        }
+        if (typeof last === "string" && (last === "paginated" || last === "filtered" || last === "sorted" || last === "search" || last === "complex")) {
+            arr.pop();
+            continue;
+        }
+        break;
+    }
+    return arr;
+}
+function isListFamilyKey(queryKey) {
+    const parts = Array.isArray(queryKey) ? queryKey : [queryKey];
+    return parts.includes("list") || parts.includes("paginated");
+}
 export function useMutation(options) {
     const queryClient = useQueryClient();
     const { optimistic, onMutate, onError, onSuccess, onSettled, ...restOptions } = options;
@@ -31,7 +51,7 @@ export function useMutation(options) {
                 return { userContext };
             }
             try {
-                await queryClient.cancelQueries({ queryKey: optimistic.queryKey });
+                await queryClient.cancelQueries({ queryKey: optimistic.queryKey, exact: true });
                 const previousData = queryClient.getQueryData(optimistic.queryKey);
                 let mappedVariables = variables;
                 if (optimistic.fieldMapping && typeof variables === "object" && variables !== null) {
@@ -44,14 +64,7 @@ export function useMutation(options) {
                         }
                     });
                 }
-                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);
-                }
+                queryClient.setQueryData(optimistic.queryKey, (oldData) => optimistic.updater(oldData, mappedVariables));
                 const mutateCallback = onMutate;
                 const userContext = onMutate ? await mutateCallback(variables) : undefined;
                 return { previousData, userContext };
@@ -76,8 +89,38 @@ export function useMutation(options) {
             }
         };
         mutationConfig.onSuccess = (data, variables, context) => {
-            const scope = optimistic.invalidateScope === "prefix" && optimistic.invalidatePrefixKey ? optimistic.invalidatePrefixKey : optimistic.queryKey;
-            queryClient.invalidateQueries({ queryKey: scope });
+            const scope = optimistic.invalidateScope ?? (isListFamilyKey(optimistic.queryKey) ? "family" : "exact");
+            const invalidations = [];
+            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 (invalidations.length > 0) {
+                const seen = new Set();
+                const tasks = invalidations
+                    .map((cfg) => ({ ...cfg, exact: false }))
+                    .filter((cfg) => {
+                    const key = JSON.stringify(cfg.queryKey);
+                    if (seen.has(key))
+                        return false;
+                    seen.add(key);
+                    return true;
+                });
+                if (tasks.length === 1) {
+                    queryClient.invalidateQueries(tasks[0]);
+                }
+                else if (tasks.length > 1) {
+                    invalidateQueriesBatch(queryClient, tasks);
+                }
+            }
             if (onSuccess) {
                 const successCallback = onSuccess;
                 successCallback(data, variables, context?.userContext);
@@ -97,7 +140,15 @@ export function setupMutationDefaults(queryClient, config) {
 }
 export function useListMutation(mutationFn, queryKey, options) {
     const queryClient = useQueryClient();
-    return useTanStackMutation({ mutationFn, onSettled: () => { queryClient.invalidateQueries({ queryKey }); }, ...options, mutationKey: options?.mutationKey });
+    return useTanStackMutation({
+        mutationFn,
+        onSettled: () => {
+            const familyKey = deriveFamilyKey(queryKey);
+            queryClient.invalidateQueries({ queryKey: familyKey, exact: false });
+        },
+        ...options,
+        mutationKey: options?.mutationKey
+    });
 }
 export function useBatchMutation(mutationFn, options) {
     return useTanStackMutation({ mutationFn, ...options, mutationKey: options?.mutationKey });
@@ -115,7 +166,7 @@ export function useConditionalOptimisticMutation(mutationFn, condition, options)
                 return { userContext, conditionMet: false };
             }
             try {
-                await queryClient.cancelQueries({ queryKey: optimistic.queryKey });
+                await queryClient.cancelQueries({ queryKey: optimistic.queryKey, exact: true });
                 const previousData = queryClient.getQueryData(optimistic.queryKey);
                 queryClient.setQueryData(optimistic.queryKey, (oldData) => optimistic.updater(oldData, variables));
                 const mutateCallback = onMutate;
@@ -149,7 +200,38 @@ export function useConditionalOptimisticMutation(mutationFn, condition, options)
         };
         mutationConfig.onSettled = (data, error, variables, context) => {
             if (context?.conditionMet) {
-                queryClient.invalidateQueries({ queryKey: optimistic.queryKey });
+                const scope = optimistic.invalidateScope ?? (isListFamilyKey(optimistic.queryKey) ? "family" : "exact");
+                const invalidations = [];
+                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 (invalidations.length > 0) {
+                    const seen = new Set();
+                    const tasks = invalidations
+                        .map((cfg) => ({ ...cfg, exact: false }))
+                        .filter((cfg) => {
+                        const key = JSON.stringify(cfg.queryKey);
+                        if (seen.has(key))
+                            return false;
+                        seen.add(key);
+                        return true;
+                    });
+                    if (tasks.length === 1) {
+                        queryClient.invalidateQueries(tasks[0]);
+                    }
+                    else if (tasks.length > 1) {
+                        invalidateQueriesBatch(queryClient, tasks);
+                    }
+                }
             }
             if (onSettled) {
                 const settledCallback = onSettled;

package/dist/types/consistency.d.ts

@@ -0,0 +1,13 @@
+import type { QueryKey } from "@tanstack/react-query";
+export type ConsistencyMode = "invalidate" | "sync+invalidate";
+export interface FamilyConsistencyOptions {
+    baseKey: QueryKey;
+    mode?: ConsistencyMode;
+    idField?: string;
+    listSelector?: (data: unknown) => unknown[] | {
+        items: unknown[];
+        total?: number;
+    } | null;
+    maxKeys?: number;
+}
+//# sourceMappingURL=consistency.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"consistency.d.ts","sourceRoot":"","sources":["../../src/types/consistency.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,iBAAiB,CAAC;AAC/D,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,QAAQ,CAAC;IAClB,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,EAAE,GAAG;QAAE,KAAK,EAAE,OAAO,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC1F,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB"}

package/dist/types/consistency.js

@@ -0,0 +1 @@
+export {};

package/dist/types/index.d.ts

@@ -18,9 +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;
+        invalidateScope?: "none" | "exact" | "family";
+        familyKey?: QueryKey;
+        relatedKeys?: QueryKey[];
     };
 }
 //# 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,CAAC;QAAC,eAAe,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;QAAC,mBAAmB,CAAC,EAAE,QAAQ,CAAC;QAAC,oBAAoB,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAC3Y"}
+{"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;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;KAC1B,CAAC;CACH"}

package/dist/utils/consistency.d.ts

@@ -0,0 +1,14 @@
+import type { QueryClient, QueryKey } from "@tanstack/react-query";
+export interface FamilyQueryMatchOptions {
+    baseKey: QueryKey;
+    maxKeys?: number;
+}
+export declare function findFamilyQueries(queryClient: QueryClient, options: FamilyQueryMatchOptions): QueryKey[];
+export declare function syncEntityAcrossFamily(queryClient: QueryClient, keys: QueryKey[], updatedEntity: unknown, options: {
+    idField?: string;
+    listSelector?: (data: unknown) => unknown[] | {
+        items: unknown[];
+        total?: number;
+    } | null;
+}): void;
+//# sourceMappingURL=consistency.d.ts.map

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

@@ -0,0 +1 @@
+{"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;AAEnE,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,QAAQ,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAiBD,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,WAAW,EAAE,OAAO,EAAE,uBAAuB,GAAG,QAAQ,EAAE,CAQxG;AAeD,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,aAAa,EAAE,OAAO,EAAE,OAAO,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,EAAE,GAAG;QAAE,KAAK,EAAE,OAAO,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,CA6BzO"}

package/dist/utils/consistency.js

@@ -0,0 +1,68 @@
+function isObjectEqual(a, b) {
+    if (typeof a === "object" && a !== null && typeof b === "object" && b !== null) {
+        return JSON.stringify(a) === JSON.stringify(b);
+    }
+    return a === b;
+}
+function startsWithKey(key, prefix) {
+    if (prefix.length > key.length)
+        return false;
+    for (let i = 0; i < prefix.length; i++) {
+        if (!isObjectEqual(key[i], prefix[i]))
+            return false;
+    }
+    return true;
+}
+export function findFamilyQueries(queryClient, options) {
+    const { baseKey, maxKeys } = options;
+    const queries = queryClient.getQueryCache().findAll({ predicate: (q) => startsWithKey(q.queryKey, baseKey) });
+    const keys = queries.map((q) => q.queryKey);
+    if (typeof maxKeys === "number" && maxKeys > 0) {
+        return keys.slice(0, maxKeys);
+    }
+    return keys;
+}
+function updateArrayById(items, updated, idField) {
+    const list = Array.isArray(items) ? items : [];
+    const id = updated[idField];
+    if (id === undefined)
+        return list;
+    return list.map((item) => {
+        const currentId = item[idField];
+        if (currentId === id) {
+            return { ...item, ...updated };
+        }
+        return item;
+    });
+}
+export function syncEntityAcrossFamily(queryClient, keys, updatedEntity, options) {
+    const idField = options.idField ?? "id";
+    keys.forEach((key) => {
+        const oldData = queryClient.getQueryData(key);
+        if (Array.isArray(oldData)) {
+            const next = updateArrayById(oldData, updatedEntity, idField);
+            queryClient.setQueryData(key, next);
+            return;
+        }
+        if (oldData && typeof oldData === "object") {
+            const selector = options.listSelector;
+            if (selector) {
+                const selected = selector(oldData);
+                if (selected === null)
+                    return;
+                if (selected && Array.isArray(selected.items)) {
+                    const nextItems = updateArrayById(selected.items, updatedEntity, idField);
+                    const next = { ...oldData, items: nextItems };
+                    queryClient.setQueryData(key, next);
+                    return;
+                }
+            }
+            if (Object.prototype.hasOwnProperty.call(oldData, "items")) {
+                const items = oldData["items"];
+                const nextItems = updateArrayById(items, updatedEntity, idField);
+                const next = { ...oldData, items: nextItems };
+                queryClient.setQueryData(key, next);
+            }
+        }
+    });
+}

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

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

package/dist/utils/optimisticUtils.js

@@ -45,7 +45,16 @@ export function createListOperationConfig(config) {
                     return oldData || [];
             }
         },
-        rollback: config.onRollback ? (previousData, error) => { config.onRollback(error, { previousData, timestamp: Date.now(), operationType: "update" }); } : undefined,
+        rollback: config.onRollback
+            ? (previousData, error) => {
+                const opType = config.operation === ListOperationType.ADD
+                    ? "create"
+                    : config.operation === ListOperationType.REMOVE
+                        ? "delete"
+                        : "update";
+                config.onRollback(error, { previousData, timestamp: Date.now(), operationType: opType });
+            }
+            : undefined,
         enabled: true
     };
 }

package/package.json

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