跳到主要内容

rxdb-plugin-workspace

⚠️ 开发中：当前版本只完整支持尚未入库的 NEW 实体草稿。已存在实体的未保存 UPDATE 暂存，以及基于 inverse patch 的公开回滚 API，仍受 RxDB 核心事件入口限制。

RxDB Workspace 插件把 NEW 实体草稿保存在内存和 IndexedDB 中，并通过 BroadcastChannel 同步同源标签页。草稿可进入 staged 状态，随后由 commit() 通过 EntityManager.save() 写入数据库。

当前语义​

  • 监听 NEW 事件并缓存完整草稿。
  • CREATE、REMOVE 或 discard() 会清理对应草稿。
  • install() 会自动读取 IndexedDB；已注册 EntityType 的草稿会恢复为 entity ref，尚未注册类型的草稿仍保留在 list() 中。
  • stagedChange() / unstageChange() 只改变提交选择，不会写数据库。
  • commit(message) 只在数据库保存成功后清理草稿；EntityType 缺失或保存失败时会 reject，并保留未提交草稿。
  • flush() 是 IndexedDB 写入屏障。写入失败时会 reject，不会在后台无限重试；修复环境后再次显式调用即可重试。
  • changes$ 在可见 workspace 状态变化时发出通知。

安装​

pnpm add @aiao/rxdb-plugin-workspace @aiao/rxdb

使用​

import { rxDBPluginWorkspace } from '@aiao/rxdb-plugin-workspace';

// db 已按所选 adapter 的文档完成配置。
db.use(rxDBPluginWorkspace, { autoSave: true });
db.init();
await db.workspace.ready;

const drafts = db.workspace.list();
await db.workspace.flush();

autoSave 默认为 true。设为 false 后，事件仍会更新内存队列和跨标签页状态，但不会自动写 IndexedDB；调用方必须在需要持久化时执行 await db.workspace.flush()。

生命周期与单实例​

一个 RxDB 实例在整个生命周期内只允许一个 workspace 实例：

  • 对同一数据库重复调用 rxDBPluginWorkspace(db) 会返回已安装实例，不会增加监听器。
  • 直接重复 new RxDBPluginWorkspace(db) 会在注册监听器前抛错。
  • 第一次安装时传入的 options 在该数据库生命周期内有效，后续重复 factory 调用不会替换配置。
  • destroy() 会移除 RxDB/BroadcastChannel 监听器、关闭 channel、停止刷盘订阅并清空内存队列；它不会隐式执行 flush()。
  • destroy() 对该 RxDB 实例是终态。需要重新安装时应创建新的 RxDB 实例。

正常使用应通过 db.use(rxDBPluginWorkspace, options) 让 RxDB 管理 install() 和 destroy()。

浏览器、SSR 与持久化边界​

插件依赖浏览器的 crypto.randomUUID() 和 IndexedDB；BroadcastChannel 可用时才启用跨标签页同步。因此不要在 SSR 渲染阶段构造插件，应在浏览器 hydration 后创建并初始化 RxDB。

IndexedDB 中的 workspace 数据是草稿副本，不是数据库事务日志。destroy()、浏览器清理站点数据或存储配额错误都可能使未刷盘数据丢失。关键流程必须显式等待 flush() 或 commit()。

通信与数据安全​

BroadcastChannel 不是鉴权或授权边界。任何同源执行上下文只要知道数据库名称，就可能向 workspace channel 发送 add/remove 消息。应用必须依赖可信 origin、CSP 和自身权限模型，不能把该通道当作安全控制。

插件不会加密草稿，也不会过滤敏感字段。草稿会以应用提供的结构写入 IndexedDB，并可能通过同源 BroadcastChannel 传输。不要把不应落盘或不应暴露给同源脚本的数据放入 workspace 草稿。

已知限制​

  • 未保存 UPDATE 暂存：未支持。 当前 RxDB 的全局 UPDATE 事件表示数据库更新已成功，不代表 Proxy 中尚未保存的编辑；插件无法只在包内可靠捕获所有实体的 EntityStatus.patches$。
  • 公开 restore/rollback：未支持。 NEW 草稿会在安装时自动恢复，但现有实体的回滚需要完整 base/inverse patch 数据模型，并依赖上述未保存 UPDATE 入口。
  • DELETE 撤销：未支持。 REMOVE/CREATE 目前只负责清理 NEW 草稿。

因此当前包不能作为完整的 Git 式 entity workspace。需要 UPDATE 暂存或回滚的调用方应等待 RxDB 核心提供可订阅的全局未保存变更 hook。

Fileoverview​

RxDB Workspace Plugin 工作空间插件，提供实体变更暂存和提交能力

主要功能：

  • 实体变更暂存（stagedChange/unstageChange）
  • 批量提交（commit）
  • IndexedDB 持久化存储
  • 变更监听和自动保存

Interfaces​

InterfaceDescription
RxDBPluginWorkspaceOptions-
WorkspaceCacheEntry-

Type Aliases​

Type AliasDescription
WorkspaceCacheId-

Variables​

VariableDescription
rxDBPluginWorkspace-