用途:为 TanStack DB 接入新后端,编写自定义集合适配器(collection adapter)。需先在 db-core 与 db-core/collection-setup 基础上阅读。
主要能力:通过 createCollection 配合 CollectionConfig 定义 getKey 与 sync;sync 函数接收 begin、write、commit、markReady、metadata 等参数,并返回清理函数。支持实时订阅、初始数据拉取、变更缓冲与回放、markReady 标记就绪。
关键用法:写入需在事务中完成,遵循 begin → write → commit。ChangeMessage 类型包括 insert、update(partial 或 full,需设置 rowUpdateMode)、delete。可选用 loadSubset 实现按需同步,配合 parseLoadSubsetOptions、parseWhereExpression、parseOrderByExpression、extractSimpleComparisons 做谓词下推。乐观状态需在服务端变更同步回集合后才结束,资料给出 Refetch、事务 ID、ID 跟踪、版本/时间戳、提供方方法五种策略。metadata 提供行级与集合级元数据,用于 resume token、cursor、LSN 等,支持持久化。
适用场景:为 WebSocket、HTTP 等新后端构建集合适配器。
限制与常见错误:未调用 markReady() 会导致 live query 无法解析、useLiveSuspenseQuery 永久挂起;先拉取后订阅会丢失期间变更,应先订阅并缓冲;write() 未配 begin() 会抛出 NoPendingSyncTransactionWriteError。