@qiaopeng/tanstack-query-plus 0.2.3 → 0.2.4

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/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,3 +1,4 @@
+import { findFamilyQueries, syncEntityAcrossFamily } from "../utils/consistency.js";
 import { useQueryClient, useMutation as useTanStackMutation } from "@tanstack/react-query";
 import { DEFAULT_MUTATION_CONFIG } from "../core/config.js";
 export function useMutation(options) {
@@ -44,14 +45,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 +70,21 @@ export function useMutation(options) {
             }
         };
         mutationConfig.onSuccess = (data, variables, context) => {
-            const scope = optimistic.invalidateScope === "prefix" && optimistic.invalidatePrefixKey ? optimistic.invalidatePrefixKey : optimistic.queryKey;
-            queryClient.invalidateQueries({ queryKey: scope });
+            queryClient.invalidateQueries({ queryKey: optimistic.queryKey });
+            const consistency = options.consistency;
+            if (consistency && Array.isArray(consistency.baseKey) && consistency.baseKey.length > 0) {
+                try {
+                    const keys = findFamilyQueries(queryClient, { baseKey: consistency.baseKey, maxKeys: consistency.maxKeys });
+                    if (consistency.mode === "sync+invalidate") {
+                        const updatedEntity = (typeof data === "object" && data !== null) ? data : (typeof variables === "object" && variables !== null ? variables : undefined);
+                        if (updatedEntity) {
+                            syncEntityAcrossFamily(queryClient, keys, updatedEntity, { idField: consistency.idField, listSelector: consistency.listSelector });
+                        }
+                    }
+                    keys.forEach((key) => { queryClient.invalidateQueries({ queryKey: key }); });
+                }
+                catch { }
+            }
             if (onSuccess) {
                 const successCallback = onSuccess;
                 successCallback(data, variables, context?.userContext);

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

@@ -6,6 +6,7 @@ export * from "./optimistic.js";
 export * from "./persistence.js";
 export * from "./selectors.js";
 export * from "./suspense.js";
+export * from "./consistency.js";
 export interface MutationContext<TData = unknown, TContext = unknown> {
     previousData?: TData;
     userContext?: TContext;
@@ -18,9 +19,16 @@ 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;
+    };
+    consistency?: {
+        baseKey: QueryKey;
+        mode?: "invalidate" | "sync+invalidate";
+        idField?: string;
+        listSelector?: (data: unknown) => unknown[] | {
+            items: unknown[];
+            total?: number;
+        } | null;
+        maxKeys?: 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,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,cAAc,kBAAkB,CAAC;AACjC,MAAM,WAAW,eAAe,CAAC,KAAK,GAAG,OAAO,EAAE,QAAQ,GAAG,OAAO;IAAI,YAAY,CAAC,EAAE,KAAK,CAAC;IAAC,WAAW,CAAC,EAAE,QAAQ,CAAC;IAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CAAE;AAC9I,MAAM,WAAW,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,GAAG,OAAO,CAAE,SAAQ,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,CAAC;IAC7I,UAAU,CAAC,EAAE;QAAE,QAAQ,EAAE,QAAQ,CAAC;QAAC,OAAO,EAAE,CAAC,UAAU,GAAG,OAAO,EAAE,OAAO,EAAE,UAAU,GAAG,SAAS,EAAE,SAAS,EAAE,UAAU,KAAK,UAAU,GAAG,SAAS,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,QAAQ,CAAC,EAAE,CAAC,UAAU,GAAG,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,CAAA;KAAE,CAAC;IACpS,WAAW,CAAC,EAAE;QAAE,OAAO,EAAE,QAAQ,CAAC;QAAC,IAAI,CAAC,EAAE,YAAY,GAAG,iBAAiB,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,EAAE,GAAG;YAAE,KAAK,EAAE,OAAO,EAAE,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7M"}

package/dist/types/index.js

@@ -5,3 +5,4 @@ export * from "./optimistic.js";
 export * from "./persistence.js";
 export * from "./selectors.js";
 export * from "./suspense.js";
+export * from "./consistency.js";

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/index.d.ts

@@ -6,4 +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 { findFamilyQueries, syncEntityAcrossFamily, type FamilyQueryMatchOptions } from "./consistency.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,MAAM,sBAAsB,CAAC;AACxD,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"}
+{"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,MAAM,sBAAsB,CAAC;AACxD,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,iBAAiB,EAAE,sBAAsB,EAAE,KAAK,uBAAuB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/utils/index.js

@@ -6,3 +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 { findFamilyQueries, syncEntityAcrossFamily } from "./consistency.js";

package/package.json

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