尧图网站建设 
tldraw 数据层深度解析基于 tldraw/store 的记录管理、响应式查询与数据迁移体系【免费下载链接】tldrawBuild infinite canvas apps in React with the tldraw SDK. Worlds best, top-most agent recommended #1 five star SDK.项目地址: https://gitcode.com/GitHub_Trending/tl/tldrawtldraw/store是 tldraw 项目构建无限画布应用的开源 SDK底层的数据管理库负责以带类型 ID 的记录record为核心组织全部应用状态。本文以官方 API 报告 packages/store/api-report.api.md 为骨架结合仓库源码packages/store/src/lib/Store.ts、StoreSchema.ts、RecordType.ts、migrate.ts、StoreQueries.ts 等与测试用例系统讲解记录类型定义、Store 核心操作、变更追踪、响应式查询、副作用钩子、数据校验、Schema 迁移与序列化机制帮助你理解 tldraw 如何实现高性能、可同步、可迁移的客户端数据层并学会在自己的应用中复用它。一、设计哲学一切数据皆记录在深入 API 之前先理解tldraw/store的世界观一个 record记录就是一个存储在类型化 ID 之下的普通对象。这是 packages/store/README.md 开篇给出的定义。每个记录拥有一个唯一且类型化的id和typeName记录之间通过 ID 相互引用构成一个扁平的记录池而不是嵌套树记录的变更以**差异diff**形式被追踪供撤销、协作同步与响应式订阅使用记录结构的变化通过**迁移migration**体系平滑升级保证旧数据可读。这种设计让 tldraw 的画布文档shape、asset、page 等、多人协作状态与 UI 状态统一到同一个可预测的数据管道中并与tldraw/state的响应式原语Atom、Computed、Signal深度集成——整个 store 本身就是构建在一系列Atom之上的响应式系统。二、基础类型从BaseRecord到RecordId2.1BaseRecord与UnknownRecord所有记录的最基本形态由BaseRecord定义见 api-report.api.md 中BaseRecord一节export interface BaseRecordTypeName extends string, Id extends RecordIdUnknownRecord { readonly id: Id readonly typeName: TypeName }UnknownRecord则是所有记录的联合基类BaseRecordstring, RecordIdUnknownRecord。只要一个对象拥有id与typeName两个只读字段它就是一个合法的 store 记录。2.2 类型化 IDRecordId、IdOf、RecordFromIdstore 的 ID 不是普通字符串而是携带类型的字符串字面量export type RecordIdR extends UnknownRecord string { __type__: R } export type IdOfR extends UnknownRecord R[id] export type RecordFromIdK extends RecordIdUnknownRecord K extends RecordIdinfer R ? R : never这一品牌字符串技巧让 TypeScript 能在编译期区分book:abc与author:xyz从而在store.get(id)时自动推断返回的记录类型。反向转换由RecordFromId完成——给定一个RecordIdBook即可还原出Book类型本身。2.3assertIdType运行时断言工具用于在不可信输入如网络消息中确认 ID 属于某记录类型export function assertIdTypeR extends UnknownRecord( id: string | undefined, type: RecordTypeR, any ): asserts id is IdOfR若断言失败会直接抛出错误常用于协作同步的入口处校验对方传来的 ID。三、定义记录类型RecordType与createRecordType3.1RecordType类的职责RecordType是记录类型的运行时化身它同时承担工厂创建记录、校验器验证数据、类型守卫isInstance / isId三重职责。核心配置与成员如下见 RecordType.ts成员类型/签名说明typeNameR[typeName]该类型的唯一名称createDefaultProperties() OmitR, id\|typeName新建记录时的默认属性工厂validatorStoreValidatorR校验函数缺省时退化为恒等函数scopeRecordScope持久化/同步范围默认documentephemeralKeys/ephemeralKeySet键名映射 / Set标记不参与快照与同步的瞬态字段create(properties)(props) R合并默认属性并自动生成 IDclone(record)(r) R深拷贝并生成新 IDcreateId(custom?)() IdOfR生成typeName:xxx形式的 IDisId(id?)类型守卫判断字符串是否为该类型的 IDisInstance(record?)类型守卫判断对象是否属于该类型parseId(id)(id) string剥离类型前缀取出唯一部分validate(record, before?)校验并返回规范记录供 Store 写入前调用withDefaultProperties(fn)派生新类型增加/覆盖默认属性create的实现揭示了 ID 生成的规则先用createDefaultProperties()填充默认值再合并传入属性最后强制写入typeName若调用方未显式提供id则自动调用createId()生成见 RecordType.ts。3.2 一个完整的记录定义示例结合 packages/store/README.md 的 Book / Author 示例实际使用方式如下import { createRecordType, BaseRecord, RecordId } from tldraw/store interface Author extends BaseRecordauthor { name: string isPseudonym: boolean } // 无默认属性isPseudonym 成为必填 const Author createRecordTypeAuthor(author) // 带默认属性isPseudonym 变为可选缺省为 false const AuthorWithDefaults createRecordTypeAuthor(author).withDefaultProperties(() ({ isPseudonym: false, })) // 创建记录ID 自动生成或显式指定 const tolkeinId Author.createId(tolkein) // author:tolkein const author Author.create({ id: tolkeinId, name: J.R.R Tolkein, isPseudonym: false }) // 类型守卫与解析 Author.isId(author:anyone) // true Author.parseId(tolkeinId) // tolkein四、Store数据层的中央容器4.1 构造与基础读写Store是库的核心类Store.ts构造参数为{ schema, props, initialData?, id? }。它的核心成员与方法覆盖了记录生命周期的全部操作API签名作用put(records: R[], phaseOverride?) void批量新增记录phaseOverride: initialize用于初始化阶段update(id, updater: (r) r) void以纯函数方式更新单条记录remove(ids: IdOfR[]) void按 ID 批量删除get(id) RecordFromIdK \| undefined按 ID 读取响应式捕获unsafeGetWithoutCapture(id) R \| undefined读取但不建立响应式依赖has/allRecords/clear—判断存在 / 全量读取 / 清空serialize(scope?)() SerializedStoreR导出纯 JSON 记录集getStoreSnapshot(scope?)() StoreSnapshotR导出数据 Schema完整快照loadStoreSnapshot(snapshot)—从快照恢复含迁移migrateSnapshot(snapshot)—对快照执行迁移后返回新快照listen(listener, filters?)() void订阅历史变更返回取消函数mergeRemoteChanges(fn)—批量执行远端变更而不触发监听器atomic(fn)() T原子事务fn 内的变更合并为一次历史记录extractingChanges(fn)() RecordsDiffR执行 fn 并返回产生的差异applyDiff(diff, opts?)—应用外部计算好的差异filterChangesByScope(diff, scope)—按 scope 过滤差异createComputedCache(name, derive, opts?)—创建派生数据缓存validate(phase)—全量校验测试/调试用基础用法来自 READMEconst store new Store({ schema, props: {} }) store.put([Author.create({ id: tolkeinId, name: J.R.R Tolkein })]) store.update(tolkeinId, (author) ({ ...author, name: DJJ Tolkz })) store.remove([tolkeinId])注意 README 的历史 APIRecordStore在新版中已演进为带 Schema 的Store本文以 api-report.api.md 中的现行 API 为准。4.2 内部实现基于 Atom 的响应式存储从源码看Store 的内部数据载体是AtomMap一个值均为Atom的 Map历史则是一个带historyLength: 1000上限的Atomnumber, RecordsDiffRStore.ts。这意味着每次get读取都会建立响应式依赖记录变化会触发tldraw/state的派生重算historyatom 的值是自增 epoch变化载荷是RecordsDiff供撤销栈、协作层与 UI 订阅使用借助atomic()与mergeRemoteChanges()多步操作可合并为单次历史条目。五、变更追踪RecordsDiff 与历史订阅5.1 差异结构RecordsDiff与CollectionDiffstore 用三类差异描述任意变更api-report.api.mdexport interface RecordsDiffR extends UnknownRecord { added: RecordIdOfR, R removed: RecordIdOfR, R updated: RecordIdOfR, [from: R, to: R] } export interface CollectionDiffT { added?: SetT removed?: SetT }RecordsDiff记录记录级变化新增、删除、以及[旧值, 新值]元组的更新CollectionDiff记录集合级变化一组元素被加入/移除例如索引index中某个键对应的 ID 集合的变动。配套的纯函数工具包括squashRecordDiffs(diffs, { mutateFirstDiff? })把多次变更压合成一次可用于合并事务内的多步操作reverseRecordsDiff(diff)求逆差异是撤销undo机制的核心原语isRecordsDiffEmpty(diff)判断差异是否为空避免无意义的历史条目与通知。5.2 历史条目与监听HistoryEntry将差异与来源打包export interface HistoryEntryR extends UnknownRecord UnknownRecord { changes: RecordsDiffR source: ChangeSource // user | remote }ChangeSource只有两个值user本地用户操作与remote远程同步写入。监听订阅可配合StoreListenerFilters精细控制触发条件——按sourceall | user | remote与scopeall | RecordScope过滤。在 Store.ts 的源码注释中给出了示例只想监听用户对 document 范围记录的修改时可传{ source: user, scope: document }。const unlisten store.listen((entry) { console.log(entry.source) // user 或 remote console.log(entry.changes.added, entry.changes.removed, entry.changes.updated) }, { source: all, scope: all }) // 之后调用 unlisten() 取消订阅此外IncrementalSetConstructorT是一个面向 Set 的增量构造器用于把一系列add/remove操作折叠成起始值 集合差异对是索引与派生查询内部实现增量更新的基础设施。六、响应式查询体系StoreQueriesstore.query是面向记录的声明式查询入口StoreQueries.ts全部查询返回tldraw/state的Computed即查询结果本身是响应式的——底层记录变化时结果自动失效并重算。6.1 查询表达式QueryExpression与QueryValueMatcher查询条件由类型安全的表达式描述api-report.api.mdexport type QueryValueMatcherT | { eq: T } // 等于 | { gt: number } // 大于 | { neq: T } // 不等于 export type QueryExpressionR extends object { [k in keyof R string]?: R[k] extends boolean | null | number | string | undefined ? QueryValueMatcherR[k] : R[k] extends object ? QueryExpressionR[k] : QueryValueMatcherR[k] }注意两点一是仅支持eq/gt/neq三种原子匹配器其中gt只对数值有效二是表达式支持嵌套对象路径R[k]为对象时可递归构造子表达式从而查询深层字段。6.2 查询方法族方法返回用途record(typeName, queryCreator?, name?)ComputedR \| undefined匹配 0~1 条记录无匹配返回 undefinedrecords(typeName, queryCreator?, name?)ComputedR[]匹配全部记录ids(typeName, queryCreator?, name?)ComputedSetIdOfR, CollectionDiff只取 ID 集合附带增量差异exec(typeName, query)R[]一次性执行查询非响应式index(typeName, path)RSIndexR按嵌套路径建立索引filterHistory(typeName)Computednumber, RecordsDiffR按类型过滤的历史流示例结合 Store.ts 源码注释// 按属性建索引作者 - 书籍集合 const booksByAuthor store.query.index(book, author) // 响应式查询所有有库存的书 const inStockBooks store.query.records(book, () ({ inStock: { eq: true }, })) // 单条查询根据 ID 取记录 const tolkein store.query.record(author, () ({ id: { eq: tolkeinId }, }))索引的底层类型为RSIndexR ComputedRSIndexMapR, RSIndexDiffR其中RSIndexMap是Map索引值, Set记录IDRSIndexDiff是Map索引值, CollectionDiff记录ID——即每个索引键对应的 ID 集合及其增量变化这为 React 组件等订阅方提供了 O(变化量) 级别的增量更新而非全量重算。StoreQueries内部用indexCache、historyCache两个 Map 缓存派生结果同一 typeName/path 的查询只会建立一份派生StoreQueries.ts。6.3 派生缓存createComputedCache对于从记录计算昂贵派生值的场景可用createComputedCache(name, derive, opts?)。derive以记录为输入计算缓存值记录删除时缓存自动清理CreateComputedCacheOpts允许通过areRecordsEqual/areResultsEqual自定义相等判定从而更精细地控制缓存失效粒度。const popularityCache store.createComputedCache( popular_author, (author) (author.isPseudonym ? null : computePopularity(author)) ) const p popularityCache.get(tolkeinId) // Data | undefined七、副作用钩子StoreSideEffectsstore.sideEffects提供了记录生命周期的拦截器用于实现业务规则、数据规范化、自动补全等逻辑。每个钩子都区分source: remote | user因此可以只对本地用户操作生效或只对远端同步生效。注册方法处理器类型语义registerBeforeCreateHandler(record, source) R创建前改写记录registerAfterCreateHandler(record, source) void创建后执行动作registerBeforeChangeHandler(prev, next, source) R更新前改写新值registerAfterChangeHandler(prev, next, source) void更新后执行动作registerBeforeDeleteHandler(record, source) false \| void删除前拦截返回false可阻止删除registerAfterDeleteHandler(record, source) void删除后清理动作registerOperationCompleteHandler(source) void一次操作整体完成时触发register(handlersByType)按类型批量注册一次注册多种类型的一组钩子所有register*方法都返回一个取消函数便于在组件卸载或模块销毁时解除订阅。注意handleBeforeChange返回的是替换后的新记录handleBeforeDelete通过返回false来否决删除——这是实现不可删除的系统记录等规则的天然切入点。八、数据校验Validator 与四阶段校验8.1StoreValidator与StoreValidators每个RecordType可以挂载校验器Store.tsexport interface StoreValidatorR extends UnknownRecord { validate(record: unknown): R validateUsingKnownGoodVersion?(knownGoodVersion: R, record: unknown): R }validate负责把任意输入校验并规整为合法记录validateUsingKnownGoodVersion是性能优化钩子——当 store 中已存在已知良好的同 ID 记录时可以基于它做增量校验避免全量深校验的开销。8.2 校验阶段与失败处理Store 的校验发生在四个阶段phasecreateRecord写入前、updateRecord更新前、initialize初始化加载、tests测试全量校验。校验失败会以StoreError形式上报export interface StoreError { error: Error isExistingValidationIssue: boolean phase: createRecord | initialize | tests | updateRecord recordAfter: unknown recordBefore?: unknown }在 Schema 层面StoreSchemaOptions.onValidationFailure?允许注册全局失败回调它接收包含store、record、recordBefore、phase的StoreValidationFailure对象返回一个替代记录R用于容错恢复。这在协作场景尤其重要远端传入的异常数据不应让整个画布崩溃而应通过回调降级修复。九、Schema 与数据迁移体系数据结构的演进是长期应用的必然需求tldraw/store用一套完备的迁移体系解决旧版本数据如何升级到新结构的问题。9.1 迁移的三级作用域Migration类型api-report.api.md 中Migration一节按scope分为三种scopeup签名适用场景record(oldState: UnknownRecord) UnknownRecord \| void转换单条记录最常见可配filter只处理特定记录store(oldState: SerializedStore) SerializedStore \| void转换整个 store增删记录类型、跨记录重构storage(storage: SynchronousRecordStorage) void迁移底层存储本身如键重命名每条迁移拥有id形如sequenceId/版本号即MigrationId \${string}/${number}可声明dependsOn 指定依赖的其他迁移 ID从而支持跨序列的依赖排序。9.2 迁移序列的三种创建方式// 1. 通用序列显式声明每条迁移的 scope const bookMigrations createMigrationSequence({ sequenceId: com.myapp.book, sequence: [ { id: com.myapp.book/1, scope: record, up: (record) ({ ...record, newField: default }), }, ], // retroactive 默认 true对序列加入前已存在的快照也生效 retroactive: true, }) // 2. 版本 ID 命名工具自动生成 com.myapp.book/1 形式的 ID const migrationIds createMigrationIds(com.myapp.book, { addGenre: 1, addPublisher: 2, }) // 3. 记录专用便捷函数自动补全 scope: record 与 typeName 过滤 const bookRecordMigrations createRecordMigrationSequence({ recordType: book, sequenceId: com.myapp.book, sequence: [{ id: com.myapp.book/1, up: (r) ({ ...r, genre: unknown }) }], })源码揭示了内部实现细节migrate.tscreateMigrationSequence会先调用squashDependsOn把序列尾部的StandaloneDependsOn依赖声明合并到最近一条迁移上再执行validateMigrations校验ID 唯一性、版本连续性、依赖合法性等校验失败直接抛错createRecordMigrationSequence为每条迁移自动注入scope: record与filter——过滤器逻辑为r.typeName recordType (m.filter?.(r) ?? true) (opts.filter?.(r) ?? true)即只迁移匹配类型及附加条件的记录旧版LegacyMigration/LegacyMigrations含up/down双向转换、subTypeKey/subTypeMigrations子类型迁移仍受支持用于向后兼容历史数据格式。9.3 迁移结果与失败原因export type MigrationResultT | { type: error; reason: MigrationFailureReason } | { type: success; value: T }MigrationFailureReason枚举了所有失败情形便于精确诊断与降级处理UnknownType序列中不存在该记录类型TargetVersionTooNew/TargetVersionTooOld目标版本超出可迁移范围IncompatibleSubtype/UnrecognizedSubtype子类型不兼容或无法识别MigrationError迁移函数执行过程中抛错。StoreSchema暴露了getMigrationsSince(persistedSchema)计算从持久化 Schema 到当前所需的迁移列表、migratePersistedRecord(record, persistedSchema, direction?)direction支持up | down可逆迁移用于降级/预览与migrateStoreSnapshot(snapshot, { mutateInputStore? })等入口Store.migrateSnapshot则在加载快照前自动执行所需迁移。十、序列化、持久化与记录作用域10.1 两种 Schema 序列化格式SerializedSchema是SerializedSchemaV1 | SerializedSchemaV2的联合。V1 是历史格式用storeVersionrecordVersions分别追踪 store 级与记录级版本并通过subTypeKey/subTypeVersions支持 shape 这类带子类型的记录V2 是现行格式统一为sequences: { [sequenceId]: number }的序列版本表StoreSchema.ts。源码中的upgradeSchema演示了 V1 → V2 的转换规则StoreSchema.tsstoreVersion映射为com.tldraw.store序列每个recordVersion.version映射为com.tldraw.typeName子类型映射为com.tldraw.typeName.subType。StoreSchema.serialize()总是输出 V2serializeEarliestVersion()已标记deprecated用于输出最早兼容格式。10.2 快照与存储抽象SerializedStoreRRecordIdOfR, R纯 JSON 的记录集可直接落盘或传输StoreSnapshotR{ store: SerializedStoreR, schema: SerializedSchema }数据 Schema 的完整快照是持久化与恢复的标准单位SynchronousRecordStorageR同步存储接口get/set/delete/keys/values/entries可对接 IndexedDB、localStorage 等SynchronousStorageR在其上追加getSchema()/setSchema()用于数据 Schema 同库存储的场景也是storage作用域迁移的操作对象。10.3RecordScope与瞬态字段export type RecordScope document | presence | session作用域决定记录如何被持久化与同步document随文档持久化并参与协作默认见 RecordType.tspresence仅代表在场状态光标位置、选区高亮不落盘、不进入文档历史session仅本会话有效UI 状态既不同步也不持久化。配合作用域ephemeralKeys可把记录内某些字段标记为瞬态如拖拽过程中的临时坐标这些字段不进入快照、不同步、也不参与文档级 diffapplyDiff支持ignoreEphemeralKeys选项Store.filterChangesByScope可单独抽取某作用域的变更。serialize(scope?)与getStoreSnapshot(scope?)都支持传入all | RecordScope来选择导出范围——这是将 document 数据与 presence 数据分开持久化的关键手段。十一、原子数据结构AtomMap、AtomSet 与 devFreezetldraw/store还提供了若干原子集合原语AtomMapK, V值以 Atom 包装的 Mapget建立响应式依赖getOrInsert/getOrInsertComputed支持按需初始化update提供函数式更新deleteMany批量删除并返回被删键值__unsafe__getWithoutCapture/__unsafe__hasWithoutCapture用于不捕获依赖的高性能探测。Store 内部即用AtomMapIdOfR, R存放全部记录Store.ts。AtomSetT值以 Atom 包装的 Set同样具备add/delete/has/entries等完整集合接口。devFreezeT(object)开发环境深冻结对象帮助尽早暴露意外修改共享状态的 bug生产环境为空操作无性能损失。RecordsDiff的增删改三表、squashRecordDiffs的合并逻辑与IncrementalSetConstructor的增量折叠共同构成 store 高性能增量更新的基石——这也是它能在 tldraw 这样频繁变更的画布应用中保持流畅的原因之一。十二、测试佐证与进一步阅读store 包在 packages/store/src/lib/test 下提供了系统的测试覆盖可作为理解 API 语义的活文档Store.test.ts 与 StoreListeners.test.ts覆盖 put/update/remove/get、监听器过滤source/scope、原子操作与历史条目语义StoreQueries.test.ts 与 executeQuery.test.ts验证eq/gt/neq匹配器、嵌套路径查询与索引增量更新StoreSchema.test.ts 与 migrate.test.ts验证 V1/V2 Schema 升级、迁移序列排序与失败原因枚举RecordType.test.ts验证默认属性合并、ID 生成、类型守卫与 clone 语义recordStoreFuzzing.test.ts以模糊测试方式随机施放记录操作验证squashRecordDiffs/reverseRecordsDiff等差异原语在任意操作序列下的一致性。若想进一步追踪调用关系可以按以下路径深入响应式基础来自 packages/stateSchema 类型定义可参考 packages/tlschema而 tldraw 编辑器如何将 shape/asset/page 等记录接入 store 的完整示例见 packages/tldraw 与 packages/editor。结语tldraw/store用一套小而精的抽象解决了通用数据层的大部分难题RecordType提供了类型安全的记录工厂与校验Store提供了响应式的读写与历史追踪StoreQueries提供了增量更新的声明式查询StoreSideEffects提供了业务逻辑钩子而迁移体系则让数据结构可以安全地长期演进。理解这套 API 报告所描述的设计不仅能帮助你读懂 tldraw 画布文档的存储与同步机制也能为构建自己的复杂前端数据层提供一份经过实战检验的参考蓝图。【免费下载链接】tldrawBuild infinite canvas apps in React with the tldraw SDK. Worlds best, top-most agent recommended #1 five star SDK.项目地址: https://gitcode.com/GitHub_Trending/tl/tldraw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 tldraw 数据层深度解析：基于 @tldraw/store 的记录管理、响应式查询与数据迁移体系
tldraw 数据层深度解析基于 tldraw/store 的记录管理、响应式查询与数据迁移体系【免费下载链接】tldrawBuild infinite canvas apps in React with the tldraw SDK. Worlds best, top-most agent recommended #1 five star SDK.项目地址: https://gitcode.com/GitHub_Trending/tl/tldrawtldraw/store是 tldraw 项目构建无限画布应用的开源 SDK底层的数据管理库负责以带类型 ID 的记录record为核心组织全部应用状态。本文以官方 API 报告 packages/store/api-report.api.md 为骨架结合仓库源码packages/store/src/lib/Store.ts、StoreSchema.ts、RecordType.ts、migrate.ts、StoreQueries.ts 等与测试用例系统讲解记录类型定义、Store 核心操作、变更追踪、响应式查询、副作用钩子、数据校验、Schema 迁移与序列化机制帮助你理解 tldraw 如何实现高性能、可同步、可迁移的客户端数据层并学会在自己的应用中复用它。一、设计哲学一切数据皆记录在深入 API 之前先理解tldraw/store的世界观一个 record记录就是一个存储在类型化 ID 之下的普通对象。这是 packages/store/README.md 开篇给出的定义。每个记录拥有一个唯一且类型化的id和typeName记录之间通过 ID 相互引用构成一个扁平的记录池而不是嵌套树记录的变更以**差异diff**形式被追踪供撤销、协作同步与响应式订阅使用记录结构的变化通过**迁移migration**体系平滑升级保证旧数据可读。这种设计让 tldraw 的画布文档shape、asset、page 等、多人协作状态与 UI 状态统一到同一个可预测的数据管道中并与tldraw/state的响应式原语Atom、Computed、Signal深度集成——整个 store 本身就是构建在一系列Atom之上的响应式系统。二、基础类型从BaseRecord到RecordId2.1BaseRecord与UnknownRecord所有记录的最基本形态由BaseRecord定义见 api-report.api.md 中BaseRecord一节export interface BaseRecordTypeName extends string, Id extends RecordIdUnknownRecord { readonly id: Id readonly typeName: TypeName }UnknownRecord则是所有记录的联合基类BaseRecordstring, RecordIdUnknownRecord。只要一个对象拥有id与typeName两个只读字段它就是一个合法的 store 记录。2.2 类型化 IDRecordId、IdOf、RecordFromIdstore 的 ID 不是普通字符串而是携带类型的字符串字面量export type RecordIdR extends UnknownRecord string { __type__: R } export type IdOfR extends UnknownRecord R[id] export type RecordFromIdK extends RecordIdUnknownRecord K extends RecordIdinfer R ? R : never这一品牌字符串技巧让 TypeScript 能在编译期区分book:abc与author:xyz从而在store.get(id)时自动推断返回的记录类型。反向转换由RecordFromId完成——给定一个RecordIdBook即可还原出Book类型本身。2.3assertIdType运行时断言工具用于在不可信输入如网络消息中确认 ID 属于某记录类型export function assertIdTypeR extends UnknownRecord( id: string | undefined, type: RecordTypeR, any ): asserts id is IdOfR若断言失败会直接抛出错误常用于协作同步的入口处校验对方传来的 ID。三、定义记录类型RecordType与createRecordType3.1RecordType类的职责RecordType是记录类型的运行时化身它同时承担工厂创建记录、校验器验证数据、类型守卫isInstance / isId三重职责。核心配置与成员如下见 RecordType.ts成员类型/签名说明typeNameR[typeName]该类型的唯一名称createDefaultProperties() OmitR, id\|typeName新建记录时的默认属性工厂validatorStoreValidatorR校验函数缺省时退化为恒等函数scopeRecordScope持久化/同步范围默认documentephemeralKeys/ephemeralKeySet键名映射 / Set标记不参与快照与同步的瞬态字段create(properties)(props) R合并默认属性并自动生成 IDclone(record)(r) R深拷贝并生成新 IDcreateId(custom?)() IdOfR生成typeName:xxx形式的 IDisId(id?)类型守卫判断字符串是否为该类型的 IDisInstance(record?)类型守卫判断对象是否属于该类型parseId(id)(id) string剥离类型前缀取出唯一部分validate(record, before?)校验并返回规范记录供 Store 写入前调用withDefaultProperties(fn)派生新类型增加/覆盖默认属性create的实现揭示了 ID 生成的规则先用createDefaultProperties()填充默认值再合并传入属性最后强制写入typeName若调用方未显式提供id则自动调用createId()生成见 RecordType.ts。3.2 一个完整的记录定义示例结合 packages/store/README.md 的 Book / Author 示例实际使用方式如下import { createRecordType, BaseRecord, RecordId } from tldraw/store interface Author extends BaseRecordauthor { name: string isPseudonym: boolean } // 无默认属性isPseudonym 成为必填 const Author createRecordTypeAuthor(author) // 带默认属性isPseudonym 变为可选缺省为 false const AuthorWithDefaults createRecordTypeAuthor(author).withDefaultProperties(() ({ isPseudonym: false, })) // 创建记录ID 自动生成或显式指定 const tolkeinId Author.createId(tolkein) // author:tolkein const author Author.create({ id: tolkeinId, name: J.R.R Tolkein, isPseudonym: false }) // 类型守卫与解析 Author.isId(author:anyone) // true Author.parseId(tolkeinId) // tolkein四、Store数据层的中央容器4.1 构造与基础读写Store是库的核心类Store.ts构造参数为{ schema, props, initialData?, id? }。它的核心成员与方法覆盖了记录生命周期的全部操作API签名作用put(records: R[], phaseOverride?) void批量新增记录phaseOverride: initialize用于初始化阶段update(id, updater: (r) r) void以纯函数方式更新单条记录remove(ids: IdOfR[]) void按 ID 批量删除get(id) RecordFromIdK \| undefined按 ID 读取响应式捕获unsafeGetWithoutCapture(id) R \| undefined读取但不建立响应式依赖has/allRecords/clear—判断存在 / 全量读取 / 清空serialize(scope?)() SerializedStoreR导出纯 JSON 记录集getStoreSnapshot(scope?)() StoreSnapshotR导出数据 Schema完整快照loadStoreSnapshot(snapshot)—从快照恢复含迁移migrateSnapshot(snapshot)—对快照执行迁移后返回新快照listen(listener, filters?)() void订阅历史变更返回取消函数mergeRemoteChanges(fn)—批量执行远端变更而不触发监听器atomic(fn)() T原子事务fn 内的变更合并为一次历史记录extractingChanges(fn)() RecordsDiffR执行 fn 并返回产生的差异applyDiff(diff, opts?)—应用外部计算好的差异filterChangesByScope(diff, scope)—按 scope 过滤差异createComputedCache(name, derive, opts?)—创建派生数据缓存validate(phase)—全量校验测试/调试用基础用法来自 READMEconst store new Store({ schema, props: {} }) store.put([Author.create({ id: tolkeinId, name: J.R.R Tolkein })]) store.update(tolkeinId, (author) ({ ...author, name: DJJ Tolkz })) store.remove([tolkeinId])注意 README 的历史 APIRecordStore在新版中已演进为带 Schema 的Store本文以 api-report.api.md 中的现行 API 为准。4.2 内部实现基于 Atom 的响应式存储从源码看Store 的内部数据载体是AtomMap一个值均为Atom的 Map历史则是一个带historyLength: 1000上限的Atomnumber, RecordsDiffRStore.ts。这意味着每次get读取都会建立响应式依赖记录变化会触发tldraw/state的派生重算historyatom 的值是自增 epoch变化载荷是RecordsDiff供撤销栈、协作层与 UI 订阅使用借助atomic()与mergeRemoteChanges()多步操作可合并为单次历史条目。五、变更追踪RecordsDiff 与历史订阅5.1 差异结构RecordsDiff与CollectionDiffstore 用三类差异描述任意变更api-report.api.mdexport interface RecordsDiffR extends UnknownRecord { added: RecordIdOfR, R removed: RecordIdOfR, R updated: RecordIdOfR, [from: R, to: R] } export interface CollectionDiffT { added?: SetT removed?: SetT }RecordsDiff记录记录级变化新增、删除、以及[旧值, 新值]元组的更新CollectionDiff记录集合级变化一组元素被加入/移除例如索引index中某个键对应的 ID 集合的变动。配套的纯函数工具包括squashRecordDiffs(diffs, { mutateFirstDiff? })把多次变更压合成一次可用于合并事务内的多步操作reverseRecordsDiff(diff)求逆差异是撤销undo机制的核心原语isRecordsDiffEmpty(diff)判断差异是否为空避免无意义的历史条目与通知。5.2 历史条目与监听HistoryEntry将差异与来源打包export interface HistoryEntryR extends UnknownRecord UnknownRecord { changes: RecordsDiffR source: ChangeSource // user | remote }ChangeSource只有两个值user本地用户操作与remote远程同步写入。监听订阅可配合StoreListenerFilters精细控制触发条件——按sourceall | user | remote与scopeall | RecordScope过滤。在 Store.ts 的源码注释中给出了示例只想监听用户对 document 范围记录的修改时可传{ source: user, scope: document }。const unlisten store.listen((entry) { console.log(entry.source) // user 或 remote console.log(entry.changes.added, entry.changes.removed, entry.changes.updated) }, { source: all, scope: all }) // 之后调用 unlisten() 取消订阅此外IncrementalSetConstructorT是一个面向 Set 的增量构造器用于把一系列add/remove操作折叠成起始值 集合差异对是索引与派生查询内部实现增量更新的基础设施。六、响应式查询体系StoreQueriesstore.query是面向记录的声明式查询入口StoreQueries.ts全部查询返回tldraw/state的Computed即查询结果本身是响应式的——底层记录变化时结果自动失效并重算。6.1 查询表达式QueryExpression与QueryValueMatcher查询条件由类型安全的表达式描述api-report.api.mdexport type QueryValueMatcherT | { eq: T } // 等于 | { gt: number } // 大于 | { neq: T } // 不等于 export type QueryExpressionR extends object { [k in keyof R string]?: R[k] extends boolean | null | number | string | undefined ? QueryValueMatcherR[k] : R[k] extends object ? QueryExpressionR[k] : QueryValueMatcherR[k] }注意两点一是仅支持eq/gt/neq三种原子匹配器其中gt只对数值有效二是表达式支持嵌套对象路径R[k]为对象时可递归构造子表达式从而查询深层字段。6.2 查询方法族方法返回用途record(typeName, queryCreator?, name?)ComputedR \| undefined匹配 0~1 条记录无匹配返回 undefinedrecords(typeName, queryCreator?, name?)ComputedR[]匹配全部记录ids(typeName, queryCreator?, name?)ComputedSetIdOfR, CollectionDiff只取 ID 集合附带增量差异exec(typeName, query)R[]一次性执行查询非响应式index(typeName, path)RSIndexR按嵌套路径建立索引filterHistory(typeName)Computednumber, RecordsDiffR按类型过滤的历史流示例结合 Store.ts 源码注释// 按属性建索引作者 - 书籍集合 const booksByAuthor store.query.index(book, author) // 响应式查询所有有库存的书 const inStockBooks store.query.records(book, () ({ inStock: { eq: true }, })) // 单条查询根据 ID 取记录 const tolkein store.query.record(author, () ({ id: { eq: tolkeinId }, }))索引的底层类型为RSIndexR ComputedRSIndexMapR, RSIndexDiffR其中RSIndexMap是Map索引值, Set记录IDRSIndexDiff是Map索引值, CollectionDiff记录ID——即每个索引键对应的 ID 集合及其增量变化这为 React 组件等订阅方提供了 O(变化量) 级别的增量更新而非全量重算。StoreQueries内部用indexCache、historyCache两个 Map 缓存派生结果同一 typeName/path 的查询只会建立一份派生StoreQueries.ts。6.3 派生缓存createComputedCache对于从记录计算昂贵派生值的场景可用createComputedCache(name, derive, opts?)。derive以记录为输入计算缓存值记录删除时缓存自动清理CreateComputedCacheOpts允许通过areRecordsEqual/areResultsEqual自定义相等判定从而更精细地控制缓存失效粒度。const popularityCache store.createComputedCache( popular_author, (author) (author.isPseudonym ? null : computePopularity(author)) ) const p popularityCache.get(tolkeinId) // Data | undefined七、副作用钩子StoreSideEffectsstore.sideEffects提供了记录生命周期的拦截器用于实现业务规则、数据规范化、自动补全等逻辑。每个钩子都区分source: remote | user因此可以只对本地用户操作生效或只对远端同步生效。注册方法处理器类型语义registerBeforeCreateHandler(record, source) R创建前改写记录registerAfterCreateHandler(record, source) void创建后执行动作registerBeforeChangeHandler(prev, next, source) R更新前改写新值registerAfterChangeHandler(prev, next, source) void更新后执行动作registerBeforeDeleteHandler(record, source) false \| void删除前拦截返回false可阻止删除registerAfterDeleteHandler(record, source) void删除后清理动作registerOperationCompleteHandler(source) void一次操作整体完成时触发register(handlersByType)按类型批量注册一次注册多种类型的一组钩子所有register*方法都返回一个取消函数便于在组件卸载或模块销毁时解除订阅。注意handleBeforeChange返回的是替换后的新记录handleBeforeDelete通过返回false来否决删除——这是实现不可删除的系统记录等规则的天然切入点。八、数据校验Validator 与四阶段校验8.1StoreValidator与StoreValidators每个RecordType可以挂载校验器Store.tsexport interface StoreValidatorR extends UnknownRecord { validate(record: unknown): R validateUsingKnownGoodVersion?(knownGoodVersion: R, record: unknown): R }validate负责把任意输入校验并规整为合法记录validateUsingKnownGoodVersion是性能优化钩子——当 store 中已存在已知良好的同 ID 记录时可以基于它做增量校验避免全量深校验的开销。8.2 校验阶段与失败处理Store 的校验发生在四个阶段phasecreateRecord写入前、updateRecord更新前、initialize初始化加载、tests测试全量校验。校验失败会以StoreError形式上报export interface StoreError { error: Error isExistingValidationIssue: boolean phase: createRecord | initialize | tests | updateRecord recordAfter: unknown recordBefore?: unknown }在 Schema 层面StoreSchemaOptions.onValidationFailure?允许注册全局失败回调它接收包含store、record、recordBefore、phase的StoreValidationFailure对象返回一个替代记录R用于容错恢复。这在协作场景尤其重要远端传入的异常数据不应让整个画布崩溃而应通过回调降级修复。九、Schema 与数据迁移体系数据结构的演进是长期应用的必然需求tldraw/store用一套完备的迁移体系解决旧版本数据如何升级到新结构的问题。9.1 迁移的三级作用域Migration类型api-report.api.md 中Migration一节按scope分为三种scopeup签名适用场景record(oldState: UnknownRecord) UnknownRecord \| void转换单条记录最常见可配filter只处理特定记录store(oldState: SerializedStore) SerializedStore \| void转换整个 store增删记录类型、跨记录重构storage(storage: SynchronousRecordStorage) void迁移底层存储本身如键重命名每条迁移拥有id形如sequenceId/版本号即MigrationId \${string}/${number}可声明dependsOn 指定依赖的其他迁移 ID从而支持跨序列的依赖排序。9.2 迁移序列的三种创建方式// 1. 通用序列显式声明每条迁移的 scope const bookMigrations createMigrationSequence({ sequenceId: com.myapp.book, sequence: [ { id: com.myapp.book/1, scope: record, up: (record) ({ ...record, newField: default }), }, ], // retroactive 默认 true对序列加入前已存在的快照也生效 retroactive: true, }) // 2. 版本 ID 命名工具自动生成 com.myapp.book/1 形式的 ID const migrationIds createMigrationIds(com.myapp.book, { addGenre: 1, addPublisher: 2, }) // 3. 记录专用便捷函数自动补全 scope: record 与 typeName 过滤 const bookRecordMigrations createRecordMigrationSequence({ recordType: book, sequenceId: com.myapp.book, sequence: [{ id: com.myapp.book/1, up: (r) ({ ...r, genre: unknown }) }], })源码揭示了内部实现细节migrate.tscreateMigrationSequence会先调用squashDependsOn把序列尾部的StandaloneDependsOn依赖声明合并到最近一条迁移上再执行validateMigrations校验ID 唯一性、版本连续性、依赖合法性等校验失败直接抛错createRecordMigrationSequence为每条迁移自动注入scope: record与filter——过滤器逻辑为r.typeName recordType (m.filter?.(r) ?? true) (opts.filter?.(r) ?? true)即只迁移匹配类型及附加条件的记录旧版LegacyMigration/LegacyMigrations含up/down双向转换、subTypeKey/subTypeMigrations子类型迁移仍受支持用于向后兼容历史数据格式。9.3 迁移结果与失败原因export type MigrationResultT | { type: error; reason: MigrationFailureReason } | { type: success; value: T }MigrationFailureReason枚举了所有失败情形便于精确诊断与降级处理UnknownType序列中不存在该记录类型TargetVersionTooNew/TargetVersionTooOld目标版本超出可迁移范围IncompatibleSubtype/UnrecognizedSubtype子类型不兼容或无法识别MigrationError迁移函数执行过程中抛错。StoreSchema暴露了getMigrationsSince(persistedSchema)计算从持久化 Schema 到当前所需的迁移列表、migratePersistedRecord(record, persistedSchema, direction?)direction支持up | down可逆迁移用于降级/预览与migrateStoreSnapshot(snapshot, { mutateInputStore? })等入口Store.migrateSnapshot则在加载快照前自动执行所需迁移。十、序列化、持久化与记录作用域10.1 两种 Schema 序列化格式SerializedSchema是SerializedSchemaV1 | SerializedSchemaV2的联合。V1 是历史格式用storeVersionrecordVersions分别追踪 store 级与记录级版本并通过subTypeKey/subTypeVersions支持 shape 这类带子类型的记录V2 是现行格式统一为sequences: { [sequenceId]: number }的序列版本表StoreSchema.ts。源码中的upgradeSchema演示了 V1 → V2 的转换规则StoreSchema.tsstoreVersion映射为com.tldraw.store序列每个recordVersion.version映射为com.tldraw.typeName子类型映射为com.tldraw.typeName.subType。StoreSchema.serialize()总是输出 V2serializeEarliestVersion()已标记deprecated用于输出最早兼容格式。10.2 快照与存储抽象SerializedStoreRRecordIdOfR, R纯 JSON 的记录集可直接落盘或传输StoreSnapshotR{ store: SerializedStoreR, schema: SerializedSchema }数据 Schema 的完整快照是持久化与恢复的标准单位SynchronousRecordStorageR同步存储接口get/set/delete/keys/values/entries可对接 IndexedDB、localStorage 等SynchronousStorageR在其上追加getSchema()/setSchema()用于数据 Schema 同库存储的场景也是storage作用域迁移的操作对象。10.3RecordScope与瞬态字段export type RecordScope document | presence | session作用域决定记录如何被持久化与同步document随文档持久化并参与协作默认见 RecordType.tspresence仅代表在场状态光标位置、选区高亮不落盘、不进入文档历史session仅本会话有效UI 状态既不同步也不持久化。配合作用域ephemeralKeys可把记录内某些字段标记为瞬态如拖拽过程中的临时坐标这些字段不进入快照、不同步、也不参与文档级 diffapplyDiff支持ignoreEphemeralKeys选项Store.filterChangesByScope可单独抽取某作用域的变更。serialize(scope?)与getStoreSnapshot(scope?)都支持传入all | RecordScope来选择导出范围——这是将 document 数据与 presence 数据分开持久化的关键手段。十一、原子数据结构AtomMap、AtomSet 与 devFreezetldraw/store还提供了若干原子集合原语AtomMapK, V值以 Atom 包装的 Mapget建立响应式依赖getOrInsert/getOrInsertComputed支持按需初始化update提供函数式更新deleteMany批量删除并返回被删键值__unsafe__getWithoutCapture/__unsafe__hasWithoutCapture用于不捕获依赖的高性能探测。Store 内部即用AtomMapIdOfR, R存放全部记录Store.ts。AtomSetT值以 Atom 包装的 Set同样具备add/delete/has/entries等完整集合接口。devFreezeT(object)开发环境深冻结对象帮助尽早暴露意外修改共享状态的 bug生产环境为空操作无性能损失。RecordsDiff的增删改三表、squashRecordDiffs的合并逻辑与IncrementalSetConstructor的增量折叠共同构成 store 高性能增量更新的基石——这也是它能在 tldraw 这样频繁变更的画布应用中保持流畅的原因之一。十二、测试佐证与进一步阅读store 包在 packages/store/src/lib/test 下提供了系统的测试覆盖可作为理解 API 语义的活文档Store.test.ts 与 StoreListeners.test.ts覆盖 put/update/remove/get、监听器过滤source/scope、原子操作与历史条目语义StoreQueries.test.ts 与 executeQuery.test.ts验证eq/gt/neq匹配器、嵌套路径查询与索引增量更新StoreSchema.test.ts 与 migrate.test.ts验证 V1/V2 Schema 升级、迁移序列排序与失败原因枚举RecordType.test.ts验证默认属性合并、ID 生成、类型守卫与 clone 语义recordStoreFuzzing.test.ts以模糊测试方式随机施放记录操作验证squashRecordDiffs/reverseRecordsDiff等差异原语在任意操作序列下的一致性。若想进一步追踪调用关系可以按以下路径深入响应式基础来自 packages/stateSchema 类型定义可参考 packages/tlschema而 tldraw 编辑器如何将 shape/asset/page 等记录接入 store 的完整示例见 packages/tldraw 与 packages/editor。结语tldraw/store用一套小而精的抽象解决了通用数据层的大部分难题RecordType提供了类型安全的记录工厂与校验Store提供了响应式的读写与历史追踪StoreQueries提供了增量更新的声明式查询StoreSideEffects提供了业务逻辑钩子而迁移体系则让数据结构可以安全地长期演进。理解这套 API 报告所描述的设计不仅能帮助你读懂 tldraw 画布文档的存储与同步机制也能为构建自己的复杂前端数据层提供一份经过实战检验的参考蓝图。【免费下载链接】tldrawBuild infinite canvas apps in React with the tldraw SDK. Worlds best, top-most agent recommended #1 five star SDK.项目地址: https://gitcode.com/GitHub_Trending/tl/tldraw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考