@qiaopeng/tanstack-query-plus 0.3.1 → 0.4.0

package/dist/hooks/index.d.ts

@@ -5,4 +5,6 @@ export { cancelQueriesBatch, invalidateQueriesBatch, type MutationDefaultsConfig
 export { type HoverPrefetchOptions, type InViewPrefetchOptions, type PrefetchOptions, useBatchPrefetch, useConditionalPrefetch, useHoverPrefetch, useIdlePrefetch, usePeriodicPrefetch, usePredictivePrefetch, usePriorityPrefetch, useRoutePrefetch, useSmartPrefetch } from "./usePrefetch.js";
 export { skipToken, useEnhancedQuery, type EnhancedQueryOptions, type EnhancedQueryResult } from "./useQuery.js";
 export { createSuspenseInfiniteQuery, createSuspenseQuery, useEnhancedSuspenseInfiniteQuery, useEnhancedSuspenseQuery } from "./useSuspenseQuery.js";
+export { useDataGuardQueryConfig } from "./useDataGuardQuery.js";
+export { useDataGuardMutation, type DataGuardMutationOptions } from "./useDataGuardMutation.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,sBAAsB,EACtB,0BAA0B,EAC1B,wBAAwB,EACxB,kBAAkB,EAClB,0BAA0B,EAC1B,mBAAmB,EACnB,wBAAwB,EACxB,sBAAsB,EACtB,kBAAkB,EAClB,0BAA0B,EAC1B,wBAAwB,EACxB,oBAAoB,EACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,eAAe,EACf,KAAK,sBAAsB,EAC3B,aAAa,EACb,iBAAiB,EACjB,aAAa,EACb,KAAK,oBAAoB,EACzB,oBAAoB,EACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,6BAA6B,EAAE,0BAA0B,EAAE,6BAA6B,EAAE,iCAAiC,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAC9L,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,WAAW,EAChB,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,WAAW,EACZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,gBAAgB,EAChB,sBAAsB,EACtB,gBAAgB,EAChB,eAAe,EACf,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,KAAK,oBAAoB,EAAE,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACjH,OAAO,EAAE,2BAA2B,EAAE,mBAAmB,EAAE,gCAAgC,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,sBAAsB,EACtB,0BAA0B,EAC1B,wBAAwB,EACxB,kBAAkB,EAClB,0BAA0B,EAC1B,mBAAmB,EACnB,wBAAwB,EACxB,sBAAsB,EACtB,kBAAkB,EAClB,0BAA0B,EAC1B,wBAAwB,EACxB,oBAAoB,EACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,eAAe,EACf,KAAK,sBAAsB,EAC3B,aAAa,EACb,iBAAiB,EACjB,aAAa,EACb,KAAK,oBAAoB,EACzB,oBAAoB,EACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,6BAA6B,EAAE,0BAA0B,EAAE,6BAA6B,EAAE,iCAAiC,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAC9L,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,WAAW,EAChB,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,WAAW,EACZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,gBAAgB,EAChB,sBAAsB,EACtB,gBAAgB,EAChB,eAAe,EACf,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,KAAK,oBAAoB,EAAE,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACjH,OAAO,EAAE,2BAA2B,EAAE,mBAAmB,EAAE,gCAAgC,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AACrJ,OAAO,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,EAAE,oBAAoB,EAAE,KAAK,wBAAwB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/hooks/index.js

@@ -5,3 +5,5 @@ export { cancelQueriesBatch, invalidateQueriesBatch, setQueryDataBatch, setupMut
 export { useBatchPrefetch, useConditionalPrefetch, useHoverPrefetch, useIdlePrefetch, usePeriodicPrefetch, usePredictivePrefetch, usePriorityPrefetch, useRoutePrefetch, useSmartPrefetch } from "./usePrefetch.js";
 export { skipToken, useEnhancedQuery } from "./useQuery.js";
 export { createSuspenseInfiniteQuery, createSuspenseQuery, useEnhancedSuspenseInfiniteQuery, useEnhancedSuspenseQuery } from "./useSuspenseQuery.js";
+export { useDataGuardQueryConfig } from "./useDataGuardQuery.js";
+export { useDataGuardMutation } from "./useDataGuardMutation.js";

package/dist/hooks/useDataGuardMutation.d.ts

@@ -0,0 +1,43 @@
+import type { QueryKey, UseMutationResult } from "@tanstack/react-query";
+import type { MutationOptions } from "../types/index.js";
+import type { VersionedEntity } from "../types/dataGuard.js";
+export interface DataGuardMutationOptions<TData, TError, TVariables, TContext> extends MutationOptions<TData, TError, TVariables, TContext> {
+    /** 冲突错误回调 */
+    onConflict?: (error: any) => void;
+}
+/**
+ * 带数据防护的 Mutation Hook
+ *
+ * 自动处理：
+ * 1. 乐观更新时递增版本号和更新时间戳
+ * 2. 标记最近更新的项
+ * 3. 成功后更新所有家族缓存的元数据
+ * 4. 冲突检测（409 错误）
+ * 5. 延迟清理更新标记
+ *
+ * @example
+ * ```typescript
+ * const mutation = useDataGuardMutation(
+ *   (updated) => api.updateProduct(updated.id, updated),
+ *   ['products', 'list', { page: 1, pageSize: 20 }],
+ *   {
+ *     optimistic: {
+ *       queryKey: ['products', 'list', { page: 1, pageSize: 20 }],
+ *       updater: (old, updated) => ({
+ *         ...old,
+ *         items: old?.items?.map(p => p.id === updated.id ? updated : p)
+ *       })
+ *     },
+ *     consistency: {
+ *       mode: 'sync+invalidate',
+ *       invalidationDelay: 3000
+ *     },
+ *     onConflict: (error) => {
+ *       toast.error('数据冲突，请刷新')
+ *     }
+ *   }
+ * )
+ * ```
+ */
+export declare function useDataGuardMutation<TData extends VersionedEntity = VersionedEntity, TError = Error, TVariables extends VersionedEntity = VersionedEntity, TContext = unknown>(mutationFn: (data: TVariables) => Promise<TData>, queryKey: QueryKey, options?: DataGuardMutationOptions<TData, TError, TVariables, TContext>): UseMutationResult<TData, TError, TVariables, TContext>;
+//# sourceMappingURL=useDataGuardMutation.d.ts.map

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

@@ -0,0 +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,CA2GxD"}

package/dist/hooks/useDataGuardMutation.js

@@ -0,0 +1,132 @@
+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";
+/**
+ * 带数据防护的 Mutation Hook
+ *
+ * 自动处理：
+ * 1. 乐观更新时递增版本号和更新时间戳
+ * 2. 标记最近更新的项
+ * 3. 成功后更新所有家族缓存的元数据
+ * 4. 冲突检测（409 错误）
+ * 5. 延迟清理更新标记
+ *
+ * @example
+ * ```typescript
+ * const mutation = useDataGuardMutation(
+ *   (updated) => api.updateProduct(updated.id, updated),
+ *   ['products', 'list', { page: 1, pageSize: 20 }],
+ *   {
+ *     optimistic: {
+ *       queryKey: ['products', 'list', { page: 1, pageSize: 20 }],
+ *       updater: (old, updated) => ({
+ *         ...old,
+ *         items: old?.items?.map(p => p.id === updated.id ? updated : p)
+ *       })
+ *     },
+ *     consistency: {
+ *       mode: 'sync+invalidate',
+ *       invalidationDelay: 3000
+ *     },
+ *     onConflict: (error) => {
+ *       toast.error('数据冲突，请刷新')
+ *     }
+ *   }
+ * )
+ * ```
+ */
+export function useDataGuardMutation(mutationFn, queryKey, options) {
+    const queryClient = useQueryClient();
+    const { onConflict, onSuccess, optimistic, ...restOptions } = options || {};
+    // 增强的 mutation 函数：检测冲突
+    const enhancedMutationFn = async (data) => {
+        try {
+            const result = await mutationFn(data);
+            return result;
+        }
+        catch (error) {
+            // 检测冲突错误（409 Conflict）
+            if (error && typeof error === 'object' &&
+                (error.status === 409 || error.code === "CONFLICT" || error.name === "ConflictError")) {
+                onConflict?.(error);
+                throw new ConflictError(error);
+            }
+            throw error;
+        }
+    };
+    // 增强的乐观更新配置
+    const enhancedOptimistic = optimistic ? {
+        ...optimistic,
+        updater: (old, variables) => {
+            // 调用原始 updater
+            const updated = optimistic.updater(old, variables);
+            if (!updated)
+                return updated;
+            // 检查 variables.id 是否存在
+            if (variables.id === undefined || variables.id === null) {
+                return updated;
+            }
+            // 标记最近更新的项
+            const withMark = markRecentlyUpdated(updated, variables.id);
+            // 乐观更新版本号
+            if (old.version !== undefined) {
+                withMark.version = old.version + 1;
+            }
+            // 乐观更新时间戳
+            if (old.updatedAt !== undefined) {
+                withMark.updatedAt = new Date().toISOString();
+            }
+            // 更新哈希
+            if (old._hash !== undefined) {
+                withMark._hash = hashObject(withMark.items);
+            }
+            return withMark;
+        }
+    } : undefined;
+    // 增强的成功回调
+    const enhancedOnSuccess = (data, variables, onMutateResult, context) => {
+        // 更新所有家族缓存的元数据
+        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秒清理
+        // 延迟清理最近更新标记
+        setTimeout(() => {
+            // 检查 variables.id 是否存在
+            if (variables.id === undefined || variables.id === null) {
+                return;
+            }
+            const cache = queryClient.getQueryCache();
+            const queries = cache.findAll({
+                predicate: (q) => startsWithKeyPrefix(q.queryKey, familyKey)
+            });
+            queries.forEach((q) => {
+                const old = queryClient.getQueryData(q.queryKey);
+                if (old?._recentlyUpdatedIds) {
+                    const cleared = clearRecentlyUpdated(old, variables.id);
+                    queryClient.setQueryData(q.queryKey, cleared);
+                }
+            });
+        }, cleanupDelay);
+        // 调用用户的 onSuccess
+        onSuccess?.(data, variables, onMutateResult, context);
+    };
+    return useMutation({
+        ...restOptions,
+        mutationFn: enhancedMutationFn,
+        optimistic: enhancedOptimistic, // 类型复杂，暂时保留
+        onSuccess: enhancedOnSuccess,
+        onError: (error, variables, onMutateResult, context) => {
+            if (error instanceof ConflictError) {
+                // 冲突时失效所有家族缓存
+                const familyKey = Array.isArray(queryKey) ? queryKey.slice(0, -1) : [queryKey];
+                queryClient.invalidateQueries({ queryKey: familyKey });
+            }
+            // 调用用户的 onError
+            restOptions.onError?.(error, variables, onMutateResult, context);
+        }
+    });
+}

package/dist/hooks/useDataGuardQuery.d.ts

@@ -0,0 +1,28 @@
+import type { QueryKey, UseQueryOptions } from "@tanstack/react-query";
+import type { DataGuardOptions, VersionedEntity, VersionedPaginatedResponse } from "../types/dataGuard.js";
+/**
+ * Hook: 创建带数据防护的查询配置
+ *
+ * 自动根据后端返回的数据选择最佳防护策略：
+ * 1. 如果有 version 字段 → 使用版本号比较（最可靠）
+ * 2. 如果有 updatedAt 字段 → 使用时间戳比较（次优）
+ * 3. 都没有 → 使用内容哈希比较（兜底）
+ *
+ * @example
+ * ```typescript
+ * const { data } = useEnhancedQuery(
+ *   useDataGuardQueryConfig(
+ *     ['products', 'list', { page: 1, pageSize: 20 }],
+ *     () => fetchProducts(1, 20),
+ *     {
+ *       maxDataAge: 5000,
+ *       onStaleDataDetected: (info) => {
+ *         console.warn('检测到旧数据', info)
+ *       }
+ *     }
+ *   )
+ * )
+ * ```
+ */
+export declare function useDataGuardQueryConfig<T extends VersionedEntity>(queryKey: QueryKey, fetchFn: () => Promise<VersionedPaginatedResponse<T>>, options?: DataGuardOptions): Pick<UseQueryOptions<VersionedPaginatedResponse<T>>, "queryKey" | "queryFn">;
+//# sourceMappingURL=useDataGuardQuery.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useDataGuardQuery.d.ts","sourceRoot":"","sources":["../../src/hooks/useDataGuardQuery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,0BAA0B,EAAE,MAAM,uBAAuB,CAAC;AAK3G;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,eAAe,EAC/D,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,MAAM,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,EACrD,OAAO,CAAC,EAAE,gBAAgB,GACzB,IAAI,CAAC,eAAe,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC,CAwD9E"}

package/dist/hooks/useDataGuardQuery.js

@@ -0,0 +1,71 @@
+import { useQueryClient } from "@tanstack/react-query";
+import { applyDataGuard, addHashToData } from "../utils/dataGuard.js";
+import { isDev } from "../core/env.js";
+/**
+ * Hook: 创建带数据防护的查询配置
+ *
+ * 自动根据后端返回的数据选择最佳防护策略：
+ * 1. 如果有 version 字段 → 使用版本号比较（最可靠）
+ * 2. 如果有 updatedAt 字段 → 使用时间戳比较（次优）
+ * 3. 都没有 → 使用内容哈希比较（兜底）
+ *
+ * @example
+ * ```typescript
+ * const { data } = useEnhancedQuery(
+ *   useDataGuardQueryConfig(
+ *     ['products', 'list', { page: 1, pageSize: 20 }],
+ *     () => fetchProducts(1, 20),
+ *     {
+ *       maxDataAge: 5000,
+ *       onStaleDataDetected: (info) => {
+ *         console.warn('检测到旧数据', info)
+ *       }
+ *     }
+ *   )
+ * )
+ * ```
+ */
+export function useDataGuardQueryConfig(queryKey, fetchFn, options) {
+    const queryClient = useQueryClient();
+    return {
+        queryKey,
+        queryFn: async () => {
+            const newData = await fetchFn();
+            const cached = queryClient.getQueryData(queryKey);
+            // 应用数据防护
+            const { shouldReject, reason, strategy, guardDetails } = applyDataGuard(newData, cached, queryKey, options);
+            // 触发回调
+            options?.onDataGuardApplied?.({
+                strategy,
+                passed: !shouldReject,
+                details: guardDetails
+            });
+            if (shouldReject) {
+                if (isDev) {
+                    console.warn("[Data Guard] 拒绝旧数据", {
+                        reason,
+                        strategy,
+                        queryKey,
+                        guardDetails
+                    });
+                }
+                options?.onStaleDataDetected?.({
+                    reason,
+                    strategy,
+                    queryKey,
+                    cached,
+                    rejected: newData
+                });
+                return cached;
+            }
+            if (isDev) {
+                console.log("[Data Guard] 接受新数据", {
+                    strategy,
+                    guardDetails
+                });
+            }
+            // 添加哈希标记
+            return addHashToData(newData);
+        }
+    };
+}

package/dist/types/dataGuard.d.ts

@@ -0,0 +1,69 @@
+import type { QueryKey } from "@tanstack/react-query";
+/**
+ * 数据防护策略类型
+ */
+export type DataGuardStrategy = "version" | "timestamp" | "hash" | "none";
+/**
+ * 带版本控制的实体基础接口
+ */
+export interface VersionedEntity {
+    id: string | number;
+    version?: number;
+    updatedAt?: string;
+}
+/**
+ * 带版本控制的分页响应
+ */
+export interface VersionedPaginatedResponse<T> {
+    items: T[];
+    total: number;
+    page?: number;
+    pageSize?: number;
+    version?: number;
+    updatedAt?: string;
+    _hash?: string;
+    _recentlyUpdatedIds?: Set<string | number>;
+}
+/**
+ * 旧数据检测信息
+ */
+export interface StaleDataInfo {
+    reason: string;
+    strategy: DataGuardStrategy;
+    queryKey: QueryKey;
+    cached: any;
+    rejected: any;
+}
+/**
+ * 数据防护应用信息
+ */
+export interface DataGuardInfo {
+    strategy: DataGuardStrategy;
+    passed: boolean;
+    details: any;
+}
+/**
+ * 数据防护配置选项
+ */
+export interface DataGuardOptions {
+    /** 时间戳模式下，最大接受的数据年龄（毫秒），默认 10000 */
+    maxDataAge?: number;
+    /** 启用版本号检查，默认 true */
+    enableVersionCheck?: boolean;
+    /** 启用时间戳检查，默认 true */
+    enableTimestampCheck?: boolean;
+    /** 启用哈希检查（兜底），默认 true */
+    enableHashCheck?: boolean;
+    /** 检测到旧数据时的回调 */
+    onStaleDataDetected?: (info: StaleDataInfo) => void;
+    /** 应用防护时的回调 */
+    onDataGuardApplied?: (info: DataGuardInfo) => void;
+}
+/**
+ * 冲突错误类
+ */
+export declare class ConflictError extends Error {
+    details: any;
+    constructor(details: any);
+}
+//# sourceMappingURL=dataGuard.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dataGuard.d.ts","sourceRoot":"","sources":["../../src/types/dataGuard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEtD;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,WAAW,GAAG,MAAM,GAAG,MAAM,CAAC;AAE1E;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B,CAAC,CAAC;IAC3C,KAAK,EAAE,CAAC,EAAE,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mBAAmB,CAAC,EAAE,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;CAC5C;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,GAAG,CAAC;IACZ,QAAQ,EAAE,GAAG,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,GAAG,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oCAAoC;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sBAAsB;IACtB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,sBAAsB;IACtB,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,yBAAyB;IACzB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,iBAAiB;IACjB,mBAAmB,CAAC,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,IAAI,CAAC;IACpD,eAAe;IACf,kBAAkB,CAAC,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,IAAI,CAAC;CACpD;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACnB,OAAO,EAAE,GAAG;gBAAZ,OAAO,EAAE,GAAG;CAIhC"}

package/dist/types/dataGuard.js

@@ -0,0 +1,10 @@
+/**
+ * 冲突错误类
+ */
+export class ConflictError extends Error {
+    constructor(details) {
+        super("Data conflict detected");
+        this.details = details;
+        this.name = "ConflictError";
+    }
+}

package/dist/types/index.d.ts

@@ -1,5 +1,6 @@
 import type { QueryKey, UseMutationOptions } from "@tanstack/react-query";
 export * from "./base.js";
+export * from "./dataGuard.js";
 export * from "./infinite.js";
 export * from "./offline.js";
 export * from "./optimistic.js";

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,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;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"}

package/dist/types/index.js

@@ -1,4 +1,5 @@
 export * from "./base.js";
+export * from "./dataGuard.js";
 export * from "./infinite.js";
 export * from "./offline.js";
 export * from "./optimistic.js";

package/dist/utils/dataGuard.d.ts

@@ -0,0 +1,37 @@
+import type { QueryClient, QueryKey } from "@tanstack/react-query";
+import type { DataGuardOptions, DataGuardStrategy, VersionedEntity, VersionedPaginatedResponse } from "../types/dataGuard.js";
+/**
+ * 计算对象的哈希值（键排序后计算，确保一致性）
+ */
+export declare function hashObject(obj: any): string;
+/**
+ * 自适应数据防护：根据数据特征自动选择最佳防护策略
+ *
+ * 策略优先级：
+ * 1. version（版本号）- 最可靠
+ * 2. updatedAt（时间戳）- 次优
+ * 3. hash（内容哈希）- 兜底
+ */
+export declare function applyDataGuard<T extends VersionedEntity>(newData: VersionedPaginatedResponse<T>, cached: VersionedPaginatedResponse<T> | undefined, queryKey: QueryKey, options?: DataGuardOptions): {
+    shouldReject: boolean;
+    reason: string;
+    strategy: DataGuardStrategy;
+    guardDetails: any;
+};
+/**
+ * 为查询数据添加哈希标记
+ */
+export declare function addHashToData<T extends VersionedEntity>(data: VersionedPaginatedResponse<T>): VersionedPaginatedResponse<T>;
+/**
+ * 标记最近更新的项
+ */
+export declare function markRecentlyUpdated<T extends VersionedEntity>(data: VersionedPaginatedResponse<T>, updatedId: string | number): VersionedPaginatedResponse<T>;
+/**
+ * 清理最近更新的标记
+ */
+export declare function clearRecentlyUpdated<T extends VersionedEntity>(data: VersionedPaginatedResponse<T>, updatedId: string | number): VersionedPaginatedResponse<T>;
+/**
+ * 更新所有家族缓存的元数据（版本号、时间戳、哈希）
+ */
+export declare function updateFamilyMetadata<T extends VersionedEntity>(queryClient: QueryClient, familyKey: QueryKey, response: Partial<VersionedPaginatedResponse<T>>): void;
+//# sourceMappingURL=dataGuard.d.ts.map

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

@@ -0,0 +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"}

package/dist/utils/dataGuard.js

@@ -0,0 +1,243 @@
+import { startsWithKeyPrefix } from "./consistency.js";
+/**
+ * 简单的字符串哈希函数（DJB2算法变体）
+ */
+function simpleHash(str) {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+        const char = str.charCodeAt(i);
+        hash = ((hash << 5) - hash) + char;
+        hash = hash | 0; // 转换为32位整数
+    }
+    return Math.abs(hash).toString(36);
+}
+/**
+ * 对象键排序（确保一致的哈希值）
+ */
+function sortObjectKeys(obj) {
+    if (obj === null || obj === undefined)
+        return obj;
+    if (typeof obj !== 'object')
+        return obj;
+    if (Array.isArray(obj))
+        return obj.map(sortObjectKeys);
+    const sorted = {};
+    Object.keys(obj).sort().forEach(key => {
+        sorted[key] = sortObjectKeys(obj[key]);
+    });
+    return sorted;
+}
+/**
+ * 计算对象的哈希值（键排序后计算，确保一致性）
+ */
+export function hashObject(obj) {
+    try {
+        const sorted = sortObjectKeys(obj);
+        return simpleHash(JSON.stringify(sorted));
+    }
+    catch {
+        return simpleHash(String(obj));
+    }
+}
+/**
+ * 自适应数据防护：根据数据特征自动选择最佳防护策略
+ *
+ * 策略优先级：
+ * 1. version（版本号）- 最可靠
+ * 2. updatedAt（时间戳）- 次优
+ * 3. hash（内容哈希）- 兜底
+ */
+export function applyDataGuard(newData, cached, queryKey, options = {}) {
+    const { maxDataAge = 10000, enableVersionCheck = true, enableTimestampCheck = true, enableHashCheck = true } = options;
+    // 如果没有缓存，接受新数据
+    if (!cached) {
+        return {
+            shouldReject: false,
+            reason: "No cached data",
+            strategy: "none",
+            guardDetails: {}
+        };
+    }
+    let shouldReject = false;
+    let reason = "";
+    let strategy = "none";
+    let guardDetails = {};
+    // ============================================
+    // 策略1：版本号比较（最可靠）
+    // ============================================
+    if (enableVersionCheck && cached.version !== undefined && newData.version !== undefined) {
+        strategy = "version";
+        if (newData.version < cached.version) {
+            shouldReject = true;
+            reason = `版本号回退：缓存版本 ${cached.version} > 新数据版本 ${newData.version}`;
+            guardDetails = {
+                cachedVersion: cached.version,
+                newVersion: newData.version,
+                diff: cached.version - newData.version
+            };
+        }
+        else if (newData.version === cached.version) {
+            guardDetails = {
+                version: newData.version,
+                status: "identical"
+            };
+        }
+        else {
+            guardDetails = {
+                cachedVersion: cached.version,
+                newVersion: newData.version,
+                status: "updated"
+            };
+        }
+    }
+    // ============================================
+    // 策略2：时间戳比较（次优）
+    // ============================================
+    else if (enableTimestampCheck && cached.updatedAt && newData.updatedAt) {
+        strategy = "timestamp";
+        try {
+            const cachedTime = new Date(cached.updatedAt).getTime();
+            const newTime = new Date(newData.updatedAt).getTime();
+            const timeDiff = cachedTime - newTime;
+            const dataAge = Date.now() - newTime;
+            guardDetails = {
+                cachedTime: cached.updatedAt,
+                newTime: newData.updatedAt,
+                timeDiff,
+                dataAge
+            };
+            // 新数据的时间戳更旧
+            if (newTime < cachedTime) {
+                // 如果数据年龄超过阈值，拒绝
+                if (dataAge > maxDataAge) {
+                    shouldReject = true;
+                    reason = `时间戳过期：新数据时间 ${newData.updatedAt} 早于缓存 ${cached.updatedAt}，且数据年龄 ${dataAge}ms 超过阈值 ${maxDataAge}ms`;
+                }
+                else {
+                    // 数据年龄在可接受范围内，记录警告但接受
+                    guardDetails.warning = `时间戳略旧但在可接受范围内（${dataAge}ms < ${maxDataAge}ms）`;
+                }
+            }
+        }
+        catch (error) {
+            guardDetails.error = `时间戳解析失败: ${error}`;
+            // 时间戳解析失败，不使用时间戳策略
+            // 将在下一个 else if 中尝试 hash 策略
+        }
+    }
+    // ============================================
+    // 策略3：内容哈希比较（兜底）
+    // ============================================
+    else if (enableHashCheck) {
+        strategy = "hash";
+        const newHash = hashObject(newData.items);
+        const cachedHash = cached._hash;
+        guardDetails = {
+            cachedHash,
+            newHash,
+            identical: cachedHash === newHash
+        };
+        if (cachedHash && cachedHash === newHash) {
+            // 内容完全相同，不需要更新
+            shouldReject = true;
+            reason = "内容哈希相同，数据未变化";
+        }
+        else if (cachedHash && cached._recentlyUpdatedIds && cached._recentlyUpdatedIds.size > 0) {
+            // 检查最近更新的项是否被回退
+            let hasRevert = false;
+            for (const id of cached._recentlyUpdatedIds) {
+                const cachedItem = cached.items.find(item => item.id === id);
+                const newItem = newData.items.find(item => item.id === id);
+                if (cachedItem && newItem) {
+                    const cachedItemHash = hashObject(cachedItem);
+                    const newItemHash = hashObject(newItem);
+                    if (cachedItemHash !== newItemHash) {
+                        // 简单启发式：如果缓存项有更多字段，可能是新的
+                        if (Object.keys(cachedItem).length > Object.keys(newItem).length) {
+                            hasRevert = true;
+                            guardDetails.revertedItem = { id, cachedItem, newItem };
+                            break;
+                        }
+                    }
+                }
+            }
+            if (hasRevert) {
+                shouldReject = true;
+                reason = "检测到最近更新的项可能被回退";
+            }
+        }
+    }
+    return {
+        shouldReject,
+        reason,
+        strategy,
+        guardDetails
+    };
+}
+/**
+ * 为查询数据添加哈希标记
+ */
+export function addHashToData(data) {
+    return {
+        ...data,
+        _hash: hashObject(data.items)
+    };
+}
+/**
+ * 标记最近更新的项
+ */
+export function markRecentlyUpdated(data, updatedId) {
+    const recentlyUpdatedIds = new Set(data._recentlyUpdatedIds || []);
+    recentlyUpdatedIds.add(updatedId);
+    return {
+        ...data,
+        _recentlyUpdatedIds: recentlyUpdatedIds
+    };
+}
+/**
+ * 清理最近更新的标记
+ */
+export function clearRecentlyUpdated(data, updatedId) {
+    if (!data._recentlyUpdatedIds)
+        return data;
+    const recentlyUpdatedIds = new Set(data._recentlyUpdatedIds);
+    recentlyUpdatedIds.delete(updatedId);
+    return {
+        ...data,
+        _recentlyUpdatedIds: recentlyUpdatedIds.size > 0 ? recentlyUpdatedIds : undefined
+    };
+}
+/**
+ * 更新所有家族缓存的元数据（版本号、时间戳、哈希）
+ */
+export function updateFamilyMetadata(queryClient, familyKey, response) {
+    const cache = queryClient.getQueryCache();
+    const queries = cache.findAll({
+        predicate: (q) => startsWithKeyPrefix(q.queryKey, familyKey)
+    });
+    queries.forEach((q) => {
+        const old = queryClient.getQueryData(q.queryKey);
+        if (old) {
+            const updated = { ...old };
+            // 更新版本号
+            if (response.version !== undefined) {
+                updated.version = response.version;
+            }
+            else if (old.version !== undefined) {
+                updated.version = old.version + 1;
+            }
+            // 更新时间戳
+            if (response.updatedAt) {
+                updated.updatedAt = response.updatedAt;
+            }
+            else if (old.updatedAt !== undefined) {
+                updated.updatedAt = new Date().toISOString();
+            }
+            // 更新哈希
+            if (old._hash !== undefined) {
+                updated._hash = hashObject(updated.items);
+            }
+            queryClient.setQueryData(q.queryKey, updated);
+        }
+    });
+}

package/dist/utils/index.d.ts

@@ -7,4 +7,5 @@ export { createQueryKeyFactory, createSimpleQueryKeyFactory, extractParamsFromKe
 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"}
+{"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"}

package/dist/utils/index.js

@@ -7,3 +7,4 @@ export { createQueryKeyFactory, createSimpleQueryKeyFactory, extractParamsFromKe
 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,7 +1,7 @@
 {
   "name": "@qiaopeng/tanstack-query-plus",
-  "version": "0.3.1",
-  "description": "Enhanced TanStack Query toolkit: defaults, hooks, persistence, offline, utils",
+  "version": "0.4.0",
+  "description": "Enhanced TanStack Query toolkit: defaults, hooks, persistence, offline, data guard, utils",
   "author": "qiaopeng",
   "license": "MIT",
   "repository": {