用途:为 SpacetimeDB 模块构建 TypeScript 客户端,适用于 Web 应用、Node.js、Deno、Bun 等 JavaScript 运行时,实现类型安全的数据库访问、自动同步与响应式更新。
主要能力:客户端连接与订阅(subscriptionBuilder、subscribe、subscribeToAllTables)、表数据访问(iter、count、find)、表事件回调(onInsert、onDelete、onUpdate)、调用 reducer(对象语法)、身份与令牌管理;服务端模块开发涵盖表定义、reducer、生命周期钩子、事件表、视图、定时表与 procedure;React 集成提供 SpacetimeDBProvider 与 useTable。
使用方式:安装 npm install spacetimedb;Node.js 环境若无原生 fetch/WebSocket 需安装 undici。用 spacetime generate --lang typescript --out-dir ./src/module_bindings --module-path ./server 生成类型绑定。客户端从 ./module_bindings 导入 DbConnection,用 builder 配置 withUri、withDatabaseName、withToken 并订阅表。服务端用 schema({ table }) 导出,reducer 名称来自导出名,索引放在 table() 的 OPTIONS 参数。
限制与注意:不要使用不存在的 API(如 @clockworklabs/spacetimedb-sdk、connection.call、位置参数 reducer 调用);reducer 调用必须用对象语法;u64/i64 字段用 BigInt(0n、1n);reducer 事务性且必须确定性,不返回数据;视图只能用索引查找,禁用 .iter();procedure 需用 ctx.withTx();2.0 使用 .withDatabaseName() 而非 .withModuleName();事件表需显式订阅,不包含在 subscribeToAllTables() 中;不要编辑生成的绑定,应重新生成。