rxdb-adapter-wa-sqlite

RxDB 适配器，使用 wa-sqlite 在浏览器中运行 SQLite。

功能特性

本地优先: 在浏览器中通过 WebAssembly 运行完整 SQLite
零服务器: 无需后端服务器，数据存储在本地
SQLite 兼容: 支持标准 SQLite 语法和功能
响应式: 数据变化自动触发更新
高性能: 使用 Web Worker 避免阻塞主线程

何时使用

需要轻量级本地数据库（WASM 体积小）
需要 SQLite 生态兼容性
需要 FTS5 全文搜索
对启动速度和内存占用敏感的应用

与其他适配器对比

特性	wa-sqlite	sqlite-wasm	PGlite
数据库引擎	SQLite	SQLite	PostgreSQL
WASM 大小	~500KB	~800KB	~3MB
全文搜索	FTS5	FTS5	tsvector
VFS 选项	多种（IDB/OPFS）	标准	固定
成熟度	适配器稳定，VFS 分级支持	官方支持	较新

安装

npm install @aiao/rxdb @aiao/rxdb-adapter-wa-sqlite
# 或
pnpm add @aiao/rxdb @aiao/rxdb-adapter-wa-sqlite

使用

import { RxDB, SyncType } from '@aiao/rxdb';
import { RxDBAdapterWaSqlite } from '@aiao/rxdb-adapter-wa-sqlite';

const rxdb = new RxDB({
  dbName: 'app',
  context: { userId: 'current-user' },
  entities: [],
  sync: {
    local: { adapter: 'wa-sqlite' },
    type: SyncType.None
  }
});

rxdb.adapter(
  'wa-sqlite',
  db =>
    new RxDBAdapterWaSqlite(db, {
      vfs: 'IDBBatchAtomicVFS',
      async: true,
      wasmPath: '/wa-sqlite/wa-sqlite-async.wasm'
    })
);

await rxdb.connect('wa-sqlite');

VFS 选项

这些 VFS 来自 wa-sqlite 的 src/examples/*，上游未把它们声明为稳定生产 API。本包只把 IDBBatchAtomicVFS 作为默认且受支持的生产后端；其它实现必须按下表评估后显式选择。

VFS	支持等级	约束
`IDBBatchAtomicVFS`	生产支持	默认选项；IndexedDB 持久化，覆盖原子写入与多连接回归
`MemoryVFS`	仅测试	同步、非持久化
`MemoryAsyncVFS`	仅测试	asyncify、非持久化
`IDBMirrorVFS`	实验性	IndexedDB 镜像实现，升级前需重新跑持久化回归
`AccessHandlePoolVFS`	实验性	仅 dedicated Worker；依赖 OPFS sync access handle
`OPFSAdaptiveVFS`	实验性	仅 dedicated Worker
`OPFSAnyContextVFS`	实验性	支持 Window、dedicated Worker、SharedWorker；只建议只读或近只读负载
`OPFSCoopSyncVFS`	实验性	仅 dedicated Worker；不要求 SharedArrayBuffer
`OPFSWriteAheadVFS`	实验性	仅 dedicated Worker；升级前需重新验证恢复与并发行为

worker 必须与 workerInstance 成对提供，sharedWorker 必须与 sharedWorkerInstance 成对提供，两种 transport 互斥。Worker/SharedWorker 由调用方创建并持有；适配器不会替调用方 terminate()。

const worker = new Worker(new URL('./wa-sqlite.worker.js', import.meta.url), { type: 'module' });

new RxDBAdapterWaSqlite(db, {
  vfs: 'OPFSCoopSyncVFS',
  async: false,
  worker: true,
  workerInstance: worker,
  wasmPath: '/wa-sqlite/wa-sqlite.wasm'
});

公开的 WA_SQLITE_VFS_LIST 是深冻结的能力表，不能用作自定义 VFS 注册入口。

wa-sqlite 供应链

npm registry 没有本包所需的 wa-sqlite，因此依赖固定到上游不可变 commit 2bf1c59d89eb6497535a4217bc62fec68a0bb994（上游 v1.1.2 release；其 package.json 的 version 字段仍写作 1.1.1，上游未随 tag 升位），pnpm-lock.yaml 同时固定归档 SHA-512。 pnpm audit:wa-sqlite 会校验所有直接消费者、commit URL 与 lockfile integrity；升级 commit 时必须重新审计 src/examples/* 的 9 个 VFS 内部路径和能力矩阵。

备份与恢复

backup() / restore() / cleanupIncompleteRestore() 由 @aiao/rxdb-adapter-sqlite-core 提供，语义与错误码见那里。

VFS	备份 / 恢复
`MemoryVFS` / `MemoryAsyncVFS`	✅ 内存库
`IDBBatchAtomicVFS`	✅ IndexedDB，持久化 `journal_mode` 为 `delete`
其余 VFS	❌ `unsupported_combination`（`vfs`）

表中组合只在主线程连接下交付：设置了 worker / workerInstance 或 sharedWorker / sharedWorkerInstance 时，三个入口都报 unsupported_combination（transport，actual 为 worker 或 sharedWorker），不碰输出流与归档源。

npm wa-sqlite 的预编译 wasm 没有编进 FTS5，库里不会有 FTS5 虚表；含 fts5 虚表的归档（来自其他构建）在写入前被拒绝。

完整示例

参考 dev-rxdb-angular 中的集成示例。

Fileoverview

@aiao/rxdb-adapter-wa-sqlite 包入口。

浏览器侧 wa-sqlite（nicolo-ribaudo/wa-sqlite）适配器；同时承担 sqlite-wasm 适配器的基线实现 —— 两者继承同一 RxDBAdapterSqliteBase，通过不同的 createSqliteClient / VFS 加载逻辑派生。

入口分层：

core 共享类型与函数（从 @aiao/rxdb-adapter-sqlite-core 再导出）
wa-sqlite 适配器主体 RxDBAdapterWaSqlite（同时以 RxDBAdapterSqlite 别名导出，便于 sqlite-wasm / wa-sqlite 共享代码路径）
客户端 WaSqliteClient，负责 SQLite 连接、变更拦截与批量派发
加载工具 waSqliteLoad：按 VFS 选型懒加载 wa-sqlite/wasm 产物

Classes

Class	Description
RxDBAdapterSqlite	浏览器 wa-sqlite 适配器。
RxDBAdapterSqliteError	RxDB SQLite 适配器错误类
SqliteClient	浏览器 wa-sqlite 客户端。
SqliteRepository	操作实体仓库

Interfaces

Interface	Description
GenerateSqlResult	SQL 生成结果：完整的 SQL 语句与可选的参数绑定。
LoadedSqlite	waSqliteLoad 的返回值：已初始化的 SQLite API 及其注册的 VFS。
ResolvedWaSqliteClientOptions	wa-sqlite 客户端规范化后的运行参数。
RxDBAdapterSqliteBase	与后端无关的 SQLite adapter 基类。
SqliteOptions	wa-sqlite 适配器配置。
WaSqliteClientRuntime	wa-sqlite 客户端的平台运行时。
WaSqliteVfsConfig	wa-sqlite VFS 的只读能力与加载配置。
WaSqliteVfsFactory	上游 example VFS 模块暴露的最小工厂结构。

Type Aliases

Type Alias	Description
LoadModuleOptions	wa-sqlite 模块加载与客户端初始化所需配置。
SqliteRepositoryConstructor	SQLite 仓库构造函数类型。
SupportVFS	支持的虚拟文件系统类型。

Variables

Variable	Description
BATCH_TIMEOUT	变更事件批处理超时档位（毫秒）。越短延迟越低但 CPU 唤醒越频繁；越长越省电但 UI 响应延后。 - `IMMEDIATE` (0): 同步派发，仅在测试场景使用 - `FAST` (4): 约一帧内合并 - `BALANCED` (16): 默认值，约一帧（60fps） - `POWER_SAVE` (50): 移动端 / 后台场景
buildRuleGroup	生成 ruleGroup sql 查询条件
ROWID	sqlite 行 id 列名
sqliteGetTableName	获取表名
sqliteGetTableNameByMetadata	通过元数据获取表名
WA_SQLITE_MAX_DATABASE_NAME_BYTES	wa-sqlite 浏览器 VFS 接受的数据库名最大 UTF-8 字节数。
WA_SQLITE_VFS_LIST	wa-sqlite 支持的 VFS 及运行环境能力；数组、条目与嵌套选项均不可变。

Functions

Function	Description
assertWaSqliteDatabaseName	在加载浏览器 VFS 前校验数据库名。
sqliteLoad	加载 wa-sqlite 模块并注册选定 VFS。

References