react-db

用途

react-db 是 TanStack DB 的 React 绑定，用于在 React 组件中订阅集合的实时查询结果。它构建于 db-core 之上，集合设置、查询构建器和变更模式需先参考 db-core。该包重新导出了 @tanstack/db 的全部内容，在 React 项目中应统一从 @tanstack/react-db 导入。

主要能力

Hooks

useLiveQuery：支持配置对象与派生查询标识（derived query identity）。返回 data、state、collection、status、isLoading、isReady、isError、isIdle、isCleanedUp。支持静态查询、预创建集合（来自路由加载器）、以及通过返回 undefined 实现的条件查询（禁用时 status='disabled'，data=undefined）。
useLiveSuspenseQuery：data 始终有定义，不会为 undefined；必须包裹在 <Suspense> 与 <ErrorBoundary> 中。结构化捕获值属于派生标识的一部分，变化时会重新挂起。
useLiveInfiniteQuery：接收查询函数与 { pageSize } 配置，返回 data（所有已加载页的扁平数组）、fetchNextPage、hasNextPage、isFetchingNextPage。
usePacedMutations：配合 debounceStrategy（如 { wait: 500 }）对高频变更进行节流，提供 onMutate 与 mutationFn。

Includes（层级数据）

当查询在 select 中使用 includes（子查询）时，默认每个子字段是一个实时的 Collection，可在子组件中用 useLiveQuery 订阅，只有受影响的子组件会重新渲染，父组件不会。若使用 toArray()，子结果为普通数组，父组件会在子项变化时重新渲染。完整 includes 规则（关联条件、嵌套 includes、聚合）参见 db-core/live-queries/SKILL.md。

虚拟属性

实时查询结果在每行上包含只读的计算虚拟属性，可用于 where、select、orderBy：

$synced：当没有待处理的本地乐观写入影响该行时为 true，否则为 false；它不证明后端已确认。
$origin：最后一次已确认变更来自本客户端时为 "local"，否则为 "remote"。
$key：该结果的行使键。
$collectionId：来源集合 ID。

这些属性自动添加，不要持久化回存储。

使用方式

查询标识（Query identity）

结构化捕获值包含在派生标识中。仅当 DB 无法从结构化 IR 派生标识时（如 .fn.where、.fn.select、.fn.having），或在热渲染路径上作为有意的性能逃生舱口时，才使用 queryKey。1.0 之前，不透明 IR 会告警并保持旧的挂载稳定标识；缓慢或重复的派生标识工作也会告警一次；两者都指向 queryKey 逃生舱口，未提供 key 的不可哈希 IR 在 1.0 将抛出错误。

Suspense 与 Error Boundary

useLiveSuspenseQuery 必须在 <ErrorBoundary> 包裹的 <Suspense> 内使用。

路由加载器预加载

在路由加载器中 await todoCollection.preload()，组件中数据即可立即使用。完整预加载模式参见 meta-framework/SKILL.md。

适用场景

适用于需要在 React 中展示实时同步数据列表、条件查询、无限滚动分页、层级（父子）数据局部刷新、以及带乐观更新的高频输入的界面。

常见错误（限制）

关键：在 .where() 中使用 === 而非 eq()。JavaScript 的 ===、!==、<、> 会立即求值返回布尔值，应使用 eq、gt、gte、lt、lte、and、or、not 等表达式函数，否则运行时抛出 InvalidWhereExpressionError。
关键：直接赋值 useLiveQuery 结果而非解构。必须解构 { data }，否则出现 "map is not a function"。对可能被禁用的查询可用 { data: todos = [] } 处理 undefined。
关键：使用不透明查询逻辑时不提供 queryKey。函数式查询变体是不透明的运行时代码，需显式 key。
高：useLiveSuspenseQuery 未使用 Error Boundary，会在渲染期间抛错并导致整个应用崩溃。
高：重复安装 @tanstack/db 导致 "not a Collection" 错误。可用 pnpm ls @tanstack/db 诊断；多个版本时通过 pnpm overrides 或 Vite resolve.alias 修复。根因通常是某个依赖打包了自带副本，而未将 @tanstack/db 声明为 peerDependency。开发模式下检测到两个实例还会抛出 DuplicateDbInstanceError。
高：查询表达力与 IVM 约束之间的张力。查询构建器看似 SQL 但存在 SQL 没有的约束——仅支持等值连接、limit/offset 需要 orderBy、没有 select 就不能 distinct。完整约束参见 db-core/live-queries/SKILL.md。

技能介绍

用途