rxdb-adapter-sqlite-core
@aiao/rxdb 的 SQLite 适配器共享内核。它把「实体 → SQL」的映射、表名解析、规则组构建、基础 Repository 与变更事件等能力抽象为后端无关的基类，供各具体 SQLite 适配器复用。
本包一般不直接安装，而是作为
@aiao/rxdb-adapter-sqlite、@aiao/rxdb-adapter-sqlite-wasm、@aiao/rxdb-adapter-sqliteai等适配器的依赖被间接引入。
提供的能力
RxDBAdapterSqliteBase：SQLite 适配器基类，封装事务、建表与变更钩子SqliteRepository：基于 SQLite 的类型安全 Repository 实现buildRuleGroup：将查询规则编译为 SQL 条件sqliteGetTableName/sqliteGetTableNameByMetadata：实体 → 表名解析- 后端契约类型：
SqliteBackend、SqliteChangeEvent、SQLiteChangeType等
具体后端只需实现 SqliteBackend 契约即可接入。
文档
- 仓库主页：https://github.com/aiao-io/aiao
- 适配器指南见项目文档站
License
Enumerations
| Enumeration | Description |
|---|---|
| SQLiteChangeType | SQLite change type constants matching C API values |
Classes
| Class | Description |
|---|---|
| Oo1ClientBase | Shared base class for SQLite clients that wrap an oo1.DB-style runtime (@sqlite.org/sqlite-wasm, @sqliteai/sqlite-wasm, ...). |
| RxDBAdapterSqliteBase | Backend-agnostic base class for SQLite adapters. |
| RxDBAdapterSqliteError | RxDB SQLite 适配器错误类 |
| SqliteCoreKeyringStorage | Persists the keyring singleton row in the adapter's own SQLite database via adapter.internalQuery. Used by both wa-sqlite and sqliteai inheritors. |
| SqliteRepository | 操作 entity 仓库 |
| SqliteRepositoryBase | 操作 entity 仓库 |
| SqliteTreeRepository | 树形实体仓库 |
Interfaces
| Interface | Description |
|---|---|
| AdapterEncryptionFacade | Developer-facing facade exposed at adapter.encryption. Forwards to the internal Keyring. If no encrypted columns are declared anywhere in the database, every method throws EncryptedConfigurationError(code: 'no_encrypted_columns'). |
| ChangeRecordEvent | SQLite update_hook 派发的单行变更事件载荷。 由各 backend SqliteClient 收集后批量分发给 RxDB 上层。 |
| CreateSqliteClientOptions | Options for creating a SQLite client with Worker support |
| EncryptionContext | - |
| FtsField | FTS5 字段描述符 |
| GenerateSqlResult | - |
| InsertSqlOptions | 操作上下文 |
| IRxDBAdapterDataChange | RxDB adapter data change interface |
| JoinContext | - |
| Oo1Capi | - |
| Oo1ClientEvents | Oo1ClientBase 派发的事件签名表，供 EventDispatcher 类型推断。 |
| Oo1ClientLoadOptions | Oo1ClientBase.init 接受的运行期选项。 子类可通过泛型扩展（如 WaSqliteLoadOptions extends Oo1ClientLoadOptions）。 |
| Oo1Database | - |
| Oo1LoadOptions | oo1 WASM 加载选项，所有 sqlite/sqliteai 适配器共享。 |
| Oo1PreparedStatement | Structural type aliases for the oo1 API surface shared by @sqlite.org/sqlite-wasm and @sqliteai/sqlite-wasm. |
| Oo1Static | - |
| RelationPair | - |
| SqliteBackend | Abstract interface for SQLite WASM backend implementations. |
| SqliteBackendOptions | Options for opening a SQLite backend |
| SqliteBaseOptions | Base options for SQLite adapters (backend-agnostic). |
| SqliteChangeEvent | SQLite change event interface |
| SqliteClientLike | Minimal client interface for SQLite adapters. Both wa-sqlite's SqliteClient and sqliteai's SqliteaiClient satisfy this contract. |
| SqliteData | A single result set with column names and row data |
| SqliteExecResult | Result from executing SQL via a backend |
| SqliteStatement | - |
| SqliteSuccessResult | SQLite query result with timing information |
| SwitchVersionSqlItem | - |
| SwitchVersionSqlResult | - |
Type Aliases
| Type Alias | Description |
|---|---|
| OpfsFallback | Behaviour when an OPFS-backed database cannot be opened (e.g. browser without Atomics.wait, missing crossOriginIsolated, etc.). |
| RowId | SQLite row ID type (bigint) |
| SQLiteCompatibleType | SQLite compatible data types for parameter binding |
| SqliteDataType | SQLite data type names |
| SqliteResult | Alias for SqliteSuccessResult |
| TransactionFun | - |
| UpdateHookCallback | Callback for SQLite update_hook notifications |
Variables
| Variable | Description |
|---|---|
| BATCH_TIMEOUT | 变更事件批处理超时档位（毫秒）。 越短延迟越低但 CPU 唤醒越频繁；越长越省电但 UI 响应延后。 - IMMEDIATE (0): 同步派发，仅在测试场景使用 - FAST (4): 约一帧内合并 - BALANCED (16): 默认值，约一帧（60fps） - POWER_SAVE (50): 移动端 / 后台场景 |
| DEFAULT_BATCH_TIMEOUT | 默认批处理超时（毫秒），约一帧 60fps。 |
| DEFAULT_CACHE_SIZE_KB | 默认 SQLite page cache 大小（KB），50 MB。 |
| deserializeFromEnvelope | - |
| envelopePlaintextPatches | Walk top-level keys of a plaintext patch; for each key present in entity.encryptedPropertyMap, replace the value with an envelope string produced by keyring.encrypt. Non-encrypted keys are copied through. |
| MAIN_TABLE_ALIAS | 主表别名 |
| ROWID | sqlite 行 id 列名 |
| serializeForEnvelope | - |
| unenvelopePlaintextPatches | Inverse of envelopePlaintextPatches: decrypt top-level envelope strings back to plaintext. Used when applying undo/redo inversePatch. |
| WAL_AUTOCHECKPOINT_PAGES | WAL 模式下自动 checkpoint 的页阈值。 |
| WATCH_TABLES | 触发实体事件派发的系统表集合。 仅这三张表的 update_hook 事件会被上抛为 RxDBChange / RxDBBranch / RxDBMigration 事件。 |
Functions
| Function | Description |
|---|---|
| build_order_by | 构建排序 SQL |
| build_rule | 生成 rule sql 查询条件 |
| build_rule_group_join | 计算查询需要的 JOIN 字符串 |
| buildCreateFtsTableSql | 生成单个 collection 的 FTS5 外部内容虚拟表 DDL。 |
| buildFtsTriggersSql | 生成 FTS5 同步 trigger 三件套（_ai / _ad / _au）。 |
| buildOo1InitOptions | 从 Oo1LoadOptions 构造 Emscripten 模块初始化对象（喂给 sqlite3InitModule）。 |
| buildRuleGroup | 生成 ruleGroup sql 查询条件 |
| convertSwitchResultToSql | - |
| count_sql | 生成 count 查询 |
| create_table_sql | 计算创建表的 sql |
| create_tables_sql | 生成多张创建表的 SQL |
| defaultPrintErr | 默认 printErr 实现：过滤掉已知噪音后转发到 console.error。 |
| defaultWarn | 默认 warn 实现：过滤掉已知噪音后转发到 console.warn。 |
| dispatch_switch_events | 发送 switch 操作对应的本地事件 |
| execute_switch_actions | 执行 SwitchVersionSqlResult 中的 SQL 操作并发送事件 |
| executeOo1Helper | Shared SQL execution helper for any oo1.DB-shaped runtime. |
| find_by_row_ids_sql | 生成 findByRowIds 查询 |
| find_sql | 生成 find 查询 |
| format_table_alias | 格式化表别名 |
| generate_entity_count_ancestors_sql | 查询祖先节点数量 |
| generate_entity_count_descendants_sql | 查询子孙节点数量 |
| generate_entity_delete_sql | 生成删除实体的 sql 语句 |
| generate_entity_deletes_sql | 生成批量删除实体的 SQL 语句 |
| generate_entity_find_ancestors_sql | 查询祖先节点 |
| generate_entity_find_descendants_sql | 查询子孙节点 |
| generate_entity_insert_sql | 生成创建实体的 sql 语句 |
| generate_entity_inserts_sql | 生成批量创建实体的参数化 SQL |
| generate_sql | 生成 SQL 查询语句 |
| generate_table_trigger_sql | 生成表的触发器 |
| generate_tree_sql | 生成树查询 |
| generateSwitchBranchSql | 生成切换分支的 SQL 语句 |
| get_cached_regexp | 带 LRU-ish 缓存的 RegExp 工厂，供 SQLite regexp / regexp_replace 自定义函数复用。 |
| get_field_sql | 获取字段的 SQL 表示 |
| get_init_sql | 生成数据库连接初始化 PRAGMA SQL。 |
| get_or_create_relation_alias | 获取或创建关系别名 |
| get_persistent_db_file_name | 标准化数据库名为持久化文件路径。 |
| get_relation_key | 获取关系键 |
| get_rule_value | 获取规则值的 SQL 表示 |
| get_sql_operator | 获取SQL操作符 |
| get_sql_value | 获取 SQL 值表示 |
| get_sql_with_params | 将 SQL 模板和参数合并为完整 SQL |
| get_table_name | 获取表名 |
| get_table_name_by_entity_type | 通过实体类型获取表名 |
| get_table_name_by_metadata | 通过元数据获取表名 |
| get_table_name_info | 解析表名信息 |
| getEntityObjectFromResult | 从查询结果行创建实体对象 |
| getRxDBChangeEventType | Get RxDB change event type string from SQLite change type |
| getTableColumnIndexName | 获取表列索引名称 |
| handle_array_in | 处理数组字段的 in/notIn 查询 |
| handle_exists | 处理 EXISTS/NOT EXISTS 操作符 |
| handle_flatmap_contains | 处理 keyValue 字段的 contains/notContains 查询 |
| handle_rxdb_change | 处理 SQLite 变更事件，将 update_hook 触发的行变更转换为 RxDB 实体事件。 |
| isSqlResultEmpty | 检查 sqlite 结果是否为空 |
| isTableExistedSql | 检查 sqlite 表是否存在 |
| normalizeCreateEntity | 规范化创建时的实体数据 |
| normalizeSingleStatementSql | 去除末尾分号与空白，便于后续判断是否为单语句。 |
| normalizeUpdateEntity | 规范化更新时的实体数据，过滤掉只读字段 |
| process_relation_joins | 处理关系字段的 JOIN |
| quote_sql_identifier | 将标识符（表名、列名、触发器名等）转义为双引号引用的 SQL 标识符。 内部双引号使用 "" 转义，防止 SQL 注入。 |
| remove_all_triggers_sql | - |
| remove_entity_ids_from_cache | 从缓存中移除已删除实体（按 id），并将其状态标记为 removed |
| resolve_column_name | 将 JS 属性名解析为数据库列名 如果 entityMetadata 存在，优先使用 columnName 支持嵌套路径，如 keyValue.string |
| resolveLocateFile | 解析 Emscripten locateFile 钩子。 |
| rewriteOpfsProxyWorkerUrl | 把 sqlite3 内置的 OPFS proxy worker URL 重写到用户提供的路径。 |
| rxdb_adapter_mutations | 批量修改实体（创建/更新/删除） |
| rxDBColumnTypeToSqliteType | 将 RxDB 属性类型转换为 SQLite 数据类型 |
| shouldIgnoreSqliteMessage | 判断 SQLite 输出是否属于已知可忽略噪音（如 OPFS 主线程降级提示）。 |
| shouldUsePreparedStatementPath | 判断是否应当走 prepared statement 路径（而非批量 exec）。 |
| switch_branch | 切换当前活跃分支并应用所需的数据迁移。 |
| switch_transaction_id | 切换分支版本 |
| transaction_sqlite_result | 处理 SQLite 事务结果，返回实体数组 |
| transformEntityValueSqliteToJs | 将 SQLite 实体值转换为 JS 对象值 |
| transformEntityValueToSql | 将实体值转换为 SQLite 格式 |
| transformValueJsToSqlite | 将 JS 类型值转换为 SQLite 兼容类型 |
| transformValueSqliteToJs | 将 SQLite 类型值转换为 JS 类型 |
| try_process_relation_flatmap | 处理关系上的 keyValue 字段 |
| try_resolve_relation_path | 尝试解析关系路径 |
| update_entity_from_sqlite_result | 更新实体缓存 只更新已有的实体，委托给 transaction_sqlite_result |
| update_sql | - |
| validateSqliteNumericOption | 校验 SQLite 客户端的整数数值选项。 |
| withGlobalOo1LoadLock | 将一次完整的 oo1 模块加载串行化到全局唯一通道。 |
| withPatchedOpfsProxyWorker | 用 Proxy 临时替换 globalThis.Worker，把 OPFS proxy worker 的脚本 URL 重写到 opfsProxyPath。 |
| withSqliteApiConfig | 临时设置 globalThis.sqlite3ApiConfig，执行 run 后恢复原值。 |
| wrapWithComlink | Wrap a client with Comlink if Worker/SharedWorker options are provided. Otherwise return the direct client. |
References
SQliteChangeType
Renames and re-exports SQLiteChangeType