rxdb-devtools

RxDB 与浏览器 DevTools Extension 之间的开发期连接器。它通过当前页面的 window.postMessage 发送事件、数据库摘要、实体查询结果和分支操作结果。

只在开发环境启用

这个包暴露了数据库检查、查询、分支变更和断开能力，禁止在生产构建中初始化。

if (import.meta.env.DEV && typeof window !== 'undefined') {
  const { getDevToolsConnector } = await import('@aiao/rxdb-devtools');
  getDevToolsConnector().init(rxdb, getEntityMetadata);
}

调用方负责确保生产 bundle 不执行 init()。enabled: false 可用于测试或显式关闭，但不能替代构建期的开发环境门禁。

生命周期

getDevToolsConnector() 返回页面级 connector 单例。
init(rxdb, getEntityMetadata) 注册 RxDB 实例、读取实体 metadata、监听 RxDB 事件并发送 HANDSHAKE。
DevTools 返回 HANDSHAKE_ACK 后，connector 发送实时事件，并刷新握手前的内存事件缓冲区。
对同一个 RxDB 对象重复 init() 是幂等操作，不会重复握手、读取 metadata 或注册监听。
当前协议明确只支持一个 RxDB 实例。第二个不同实例会在读取其 metadata、修改映射或注册监听前抛错。
disconnect() 只断开 connector 通信、清理监听和缓冲区，不调用 rxdb.disconnectAll()。
DISCONNECT_RXDB 或 window.__AIAO_RXDB_DEVTOOLS__.disconnectRxdb() 会请求关闭 RxDB：
- graceful：disconnectAll() 成功，随后清理实例和监听；
- forced：graceful 失败，但本地 Worker 终止或 SharedWorker port 关闭成功，随后清理；
- failed：关闭、超时或强制释放失败，保留实例、监听和全局 helper，允许重试；
- not-connected：当前没有已注册实例。

SSR

init() 和 disconnect() 在没有 window 的环境中是 no-op。仍建议把动态导入和初始化放在浏览器开发环境分支内，避免服务端无意义加载。

通信与威胁模型

connector 只接受：

event.source === window；
event.origin 为空或等于当前页面 origin；
完整且无额外字段的 message envelope；
已知消息类型、合法方向和对应命令 payload。

这些检查用于拒绝 malformed 消息，不是身份认证。任何能在同一页面执行 JavaScript 的脚本，都可能构造一条完全合法的 window.postMessage 命令。把 token 放进同一个可观察、可重放的 postMessage 通道只会制造安全幻觉，因此本包不实现这种 token。

真正可信的 capability 需要 Extension 在隔离边界中建立不可由页面脚本伪造的通道；这涉及包外 Extension 协议，当前未实现。在此之前，只能把本包视为开发工具，并把页面上的第三方脚本视为同等可信。

危险命令

DISCONNECT_RXDB：关闭当前 RxDB 实例；
QUERY_ENTITY：读取指定实体，limit 仅允许缺省或 1..1000 的安全整数；
SWITCH_BRANCH：切换分支；
CREATE_BRANCH：创建分支；
DELETE_BRANCH：删除分支。

malformed envelope 或 payload 会被静默拒绝，不会进入命令 handler，也不会把非法 limit 回退成默认值。

加密字段策略

getEntityMetadata 返回的 encryptedPropertyMap 是唯一加密字段来源。connector 在初始化时建立字段映射，并执行以下规则：

QUERY_ENTITY 的结果中，metadata 声明的顶层字段始终替换为 [encrypted]；
事件 entities[].patch、entities[].inversePatch、entities[].data 使用同一遮罩规则；
非敏感字段保持不变；
只解释顶层字段名，不解析 profile.ssn 一类嵌套路径；嵌套对象中的同名字段不会被递归替换；
不提供明文 opt-in，DevTools 永远不会通过本协议请求返回 metadata 声明字段的明文；
serializer 仍会遮罩符合已知加密 envelope 格式的字符串。

如果 metadata 漏报字段，connector 无法猜测其敏感性。实体 metadata 的正确性属于上游安全契约。

Fileoverview

RxDB DevTools 集成包提供与 Chrome DevTools Extension 的通信接口

Classes

Class	Description
DevToolsConnector	RxDB DevTools 连接器。
EventBuffer	事件缓冲区在 DevTools 断开连接时缓存事件，重连后 flush
SequenceGenerator	序列号生成器类生成单调递增的序列号，用于事件排序

Interfaces

Interface	Description
ClearMessage	清除 DevTools 事件消息。
DevToolsMessage	基础消息结构。
DevToolsOptions	RxDB DevTools 配置选项。
EventMessage	事件消息。
HandshakeAckMessage	握手确认消息。
HandshakeMessage	握手消息。
PingMessage	DevTools 状态探测消息。
PongMessage	页面状态响应消息。
SerializedEvent	序列化后的 RxDB 事件。

Type Aliases

Type Alias	Description
AnyDevToolsMessage	所有合法 RxDB DevTools 消息。
DisconnectMessage	页面或 DevTools 发起的通信断开消息。
MessageDirection	RxDB DevTools 消息方向。
MessageType	RxDB DevTools 消息类型。

Variables

Variable	Description
RXDB_DEVTOOLS_MESSAGE	RxDB DevTools 消息来源标识符。

Functions

Function	Description
createMessage	消息协议类型 - RXDB_DEVTOOLS_MESSAGE: 消息来源标识符 - createMessage: 创建消息的工厂函数 - isDevToolsMessage: 类型守卫函数 - DevToolsMessage: 基础消息结构 - HandshakeMessage: 握手消息 - HandshakeAckMessage: 握手确认消息 - EventMessage: 事件消息 - SerializedEvent: 序列化后的事件 - DisconnectMessage: 断开连接消息 - ClearMessage: 清除事件消息 - PingMessage/PongMessage: 心跳消息
deserialize	反序列化事件（主要用于类型转换）
getDevToolsConnector	核心连接器 - DevToolsConnector: DevTools 连接器类 - getDevToolsConnector: 获取或创建全局连接器 - resetDevToolsConnector: 重置全局连接器
isDevToolsMessage	消息协议类型 - RXDB_DEVTOOLS_MESSAGE: 消息来源标识符 - createMessage: 创建消息的工厂函数 - isDevToolsMessage: 类型守卫函数 - DevToolsMessage: 基础消息结构 - HandshakeMessage: 握手消息 - HandshakeAckMessage: 握手确认消息 - EventMessage: 事件消息 - SerializedEvent: 序列化后的事件 - DisconnectMessage: 断开连接消息 - ClearMessage: 清除事件消息 - PingMessage/PongMessage: 心跳消息
resetDevToolsConnector	核心连接器 - DevToolsConnector: DevTools 连接器类 - getDevToolsConnector: 获取或创建全局连接器 - resetDevToolsConnector: 重置全局连接器
serialize	序列化 RxDB 事件

只在开发环境启用​

生命周期​

SSR​

通信与威胁模型​

危险命令​

加密字段策略​

Fileoverview​

Classes​

Interfaces​

Type Aliases​

Variables​

Functions​