rxdb
面向 Local-first 应用的 TypeScript 数据库核心。通过装饰器驱动的实体定义，自动生成类型安全的 Repository 与响应式查询 API，让你在浏览器中直接运行 SQLite，以接近原生 App 的方式构建离线优先、数据驱动的 Web 应用。
@aiao/rxdb 是引擎核心，与具体存储后端解耦 —— 通过适配器接入 wa-sqlite / PGlite / Supabase / sqliteai，通过框架绑定接入 Angular / React / Vue。
安装
pnpm add @aiao/rxdb rxjs
核心包不直接提供存储实现，需配合一个适配器使用，例如浏览器内 SQLite：
pnpm add @aiao/rxdb-adapter-wa-sqlite
核心能力
- 装饰器驱动实体：用
@Entity/@TreeEntity声明数据模型与字段元数据 - 类型安全 Repository：从实体自动派生 CRUD 与关系查询接口
- 响应式查询：查询结果以 RxJS Observable 形式推送，数据变更自动刷新
- 变更追踪与事务：内建 diff、变更事件与事务支持
- 适配器无关：同一套模型可运行在不同存储后端之上
快速开始
import { Entity, EntityBase } from '@aiao/rxdb';
@Entity({ name: 'todo' })
export class Todo extends EntityBase {
title!: string;
done!: boolean;
}
实体定义、查询与变更的完整用法见文档站。
文档
- 仓库主页与路线图：https://github.com/aiao-io/aiao
- API 参考、快速上手与框架集成指南见项目文档站
License
RxDB 核心包 - 响应式数据库客户端 提供实体管理、版本控制、查询管理等功能
Enumerations
| Enumeration | Description |
|---|---|
| OnDeleteAction | 外键约束操作枚举 定义 SQLite 外键约束的级联行为 |
| OnUpdateAction | 外键更新行为枚举 定义当父表主键被更新时的级联行为 |
| PropertyType | 实体属性类型枚举 定义实体属性支持的数据类型 |
| RelationKind | 实体关系类型枚举 定义实体之间可能的关系类型 |
| SyncStatus | 同步状态 |
| SyncType | 同步类型枚举 定义不同的数据同步策略，控制本地数据和远程数据之间的同步方式 |
Classes
Interfaces
Type Aliases
Variables
| Variable | Description |
|---|---|
| CONFLICT_DETECTED_EVENT | 冲突检测事件类型 |
| CONFLICT_PENDING_EVENT | 冲突待处理事件类型 |
| ENTITIES | - |
| ENTITY_BASE_METADATA_OPTIONS | - |
| ENTITY_LOCAL_CREATE_EVENT | 本地实体创建事件类型 |
| ENTITY_LOCAL_NEW_EVENT | 本地实体初始化事件类型 |
| ENTITY_LOCAL_REMOVE_EVENT | 本地实体删除事件类型 |
| ENTITY_LOCAL_UPDATE_EVENT | 本地实体更新事件类型 |
| ENTITY_REMOTE_CREATE_EVENT | 远程实体创建事件类型 |
| ENTITY_REMOTE_REMOVE_EVENT | 远程实体删除事件类型 |
| ENTITY_REMOTE_UPDATE_EVENT | 远程实体更新事件类型 |
| ENTITY_STATIC_TYPES | - |
| MERGE_BRANCH_BEGIN | 分支合并开始事件类型 |
| MERGE_BRANCH_COMMIT | 分支合并提交事件类型 |
| MERGE_BRANCH_ROLLBACK | 分支合并回滚事件类型 |
| REMOTE_CHANGES_PENDING_EVENT | 远程变更待处理事件类型 |
| REPOSITORY_SYNC_BEGIN_EVENT | Repository 同步开始事件类型 |
| REPOSITORY_SYNC_COMPLETE_EVENT | Repository 同步完成事件类型 |
| REPOSITORY_SYNC_ERROR_EVENT | Repository 同步错误事件类型 |
| SWITCH_BRANCH_BEGIN | 分支切换开始事件类型 |
| SWITCH_BRANCH_COMMIT | 分支切换提交事件类型 |
| SWITCH_BRANCH_ROLLBACK | 分支切换回滚事件类型 |
| SYNC_BEGIN_EVENT | 同步开始事件类型 |
| SYNC_COMPLETE_EVENT | 同步完成事件类型 |
| SYNC_ERROR_EVENT | 同步错误事件类型 |
| TRANSACTION_BEGIN | 事务开始事件类型 |
| TRANSACTION_COMMIT | 事务提交事件类型 |
| TRANSACTION_ROLLBACK | 事务回滚事件类型 |
| TREE_ADJACENCY_LIST_ENTITY_BASE_OPTIONS | - |
| TreeEntity | 树形实体装饰器 用于将类标记为树形结构实体，并处理树形特定的元数据 |
Functions
| Function | Description |
|---|---|
| __decorateClass | - |
| cleanupExpired | 清理不再满足过滤条件的本地过期数据 |
| compactChanges | 压缩变更列表为 SwitchVersionActions（专用于 Push 场景） |
| deterministicStringify | 确定性的 JSON.stringify 通过对 object 的键进行排序，确保相同内容但具有不同键顺序的对象能够生成相同的缓存 Key |
| diffMetadata | Compare remote metadata with local metadata to determine sync actions |
| Entity | 实体装饰器 用于将类标记为 RxDB 实体，并处理元数据、代理和生命周期 |
| extractEntityFields | - |
| extractSystemFields | - |
| fillDefaultValue | 给实体实例填充默认值 根据元数据中定义的默认值，为实体的未赋值属性设置默认值 |
| fillInitValue | 给实体实例填充初始值 根据提供的初始值对象，为实体的属性设置值，同时尊重只读属性 |
| formatEntityFieldValue | - |
| getEntityMetadata | 获取实体元数据 |
| getEntityMutations | 获取实体变更映射 |
| getEntityStatus | 获取实体状态 |
| getEntityType | 获取实体类型 |
| getNeedRemoveEntities | 获取需要删除的实体 从根实体开始递归查找所有需要删除的关联实体 注意：根实体本身不会被加入删除列表，只收集它们的关系中标记为删除的实体 |
| getNeedSaveEntities | 获取需要保存的实体 |
| getRxDBChangeKey | 构造业务实体的唯一键（用于 deletes/updates/inserts Map） |
| getSyncableRepositories | 获取需要同步的 repository 列表 |
| getSyncConfig | 获取实体的有效同步配置（支持全局配置回退） |
| getSyncType | 从 EntityMetadata 获取同步类型 |
| groupBySyncType | 按同步类型分组 repositories |
| isAdapterShutdownError | 判断错误是否由 adapter 关闭/断连引起。 |
| isEntityInternalName | 判断字段名是否是内部保留字段 包括基类字段、私有字段和以下划线开头的字段 |
| isNoSync | 检查 repository 是否完全不同步 |
| isRuleGroup | 判断是否是 RuleGroup |
| isRxDBEntity | 检查是否为 RxDB 实体 |
| needsPull | 检查 repository 是否需要 pull |
| needsPush | 检查 repository 是否需要 push |
| parseEntityFieldValue | - |
| parseRxDBChangeKey | 解析实体键 |
| queryNeedRefreshCreate | - |
| queryNeedRefreshRemove | - |
| queryNeedRefreshUpdate | - |
| setRuntimeObjectKey | 设置可重绑定的运行时属性 供 EntityManager 在不同 RxDB 实例之间重复绑定实体类时使用 |
| setSafeObjectKey | 设置安全的不可变属性 创建一个不可枚举、不可配置、不可写的属性 |
| setSafeObjectKeyLazyInitOnce | 设置懒加载属性 创建一个只在首次访问时计算值的属性，后续访问直接返回计算结果 |
| setSafeObjectWritableKey | 设置安全的可变属性 创建一个不可枚举、不可配置但可写的属性 |
| syncBranches | 从远程拉取所有分支信息并同步到本地 |
| transitionMetadata | 将元数据选项(metadataOptions)转换为实体元数据(metadata) |
| uuid | 生成 uuid v7 |
| validateEntityFieldValue | - |