rxdb-adapter-sqlite-wasm

RxDB SQLite 适配器，基于 @subframe7536/sqlite-wasm。

与 @aiao/rxdb-adapter-wa-sqlite 共享 @aiao/rxdb-adapter-sqlite-core 中的核心能力；差异在于底层 SQLite WASM 由 subframe 包提供（自定义 wa-sqlite，支持 FTS5 / UPDATE DELETE LIMIT，内置 typesafe VFS 预设）。

何时使用

需要 subframe 提供的增强 SQLite 特性（UPDATE/DELETE LIMIT）
需要类型安全的 VFS 预设
需要更灵活的 VFS 选择（包括 OPFS FileHandle）

与其他 SQLite 适配器对比

特性	sqlite-wasm	wa-sqlite	sqlite-wasm (官方)
底层库	@subframe7536/sqlite-wasm	wa-sqlite	@sqlite.org/sqlite-wasm
UPDATE/DELETE LIMIT	✅	❌	❌
VFS 预设	类型安全	手动配置	手动配置
OPFS FileHandle	✅	❌	✅
包大小	~800KB	~500KB	~1MB

支持的存储（VFS 预设）

`vfs` 取值	说明	运行环境
`memory`	纯内存，`MemoryVFS`	主线程/Worker
`idb`	IndexedDB，`IDBBatchAtomicVFS`	主线程/Worker
`idb-memory`	内存 + IndexedDB 镜像，`IDBMirrorVFS`	主线程/Worker
`opfs`	OPFS，`OPFSCoopSyncVFS`	必须 Worker
`fs-handle`	本地文件/OPFS FileHandle，`OPFSAnyContextVFS`	主线程/Worker

安装

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

走 Worker / SharedWorker（opfs 强制要求）时，Worker 文件需要你自己 import { expose } from 'comlink'，因此还要装 comlink —— 它是本包的可选 peer 依赖，严格模式的 pnpm 不会把 core 的传递依赖暴露给你：

npm install comlink
# 或
pnpm add comlink

用法

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

const rxdb = new RxDB({
  dbName: 'my-app',
  entities: [/* 实体类 */],
  sync: {
    local: { adapter: 'sqlite-wasm' },
    type: SyncType.None
  }
});

rxdb.adapter('sqlite-wasm', async db => new RxDBAdapterSqlite(db, { vfs: 'idb' }));

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

在 Worker 中运行（opfs VFS 必须 Worker）：

// sqlite-wasm.worker.ts
import { SqliteClient } from '@aiao/rxdb-adapter-sqlite-wasm';
import { expose } from 'comlink';

expose(new SqliteClient());

// 主线程：workerInstance 本身即可选择 Worker transport
rxdb.adapter(
  'sqlite-wasm',
  async db =>
    new RxDBAdapterSqlite(db, {
      vfs: 'opfs',
      worker: true,
      workerInstance: new Worker(new URL('./sqlite-wasm.worker', import.meta.url), { type: 'module' }),
      workerOwnership: 'client'
    })
);

workerOwnership 默认是 caller：同一个 Worker 可在 disconnect 后建立新连接，但调用方最终必须执行 worker.terminate()。像上例一样在 adapter 工厂内创建 Worker 时，应使用 client，这样断开或初始化失败都会释放 Comlink 端口并终止线程。

直接调用 createSqliteClient 时，先 await client.disconnect()，再调用包根入口导出的 releaseComlinkProxy(client)；RxDBAdapterSqlite 已在 disconnect() 内自动完成代理释放。

备份与恢复

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

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

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

完整示例

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

Fileoverview

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

浏览器侧 @subframe7536/sqlite-wasm 适配器。结构与 rxdb-adapter-wa-sqlite 一一对应，只是底层 SQLite 实现换成 sqlite-wasm + 派生 VFS 加载逻辑。

入口分层：

core 共享类型与函数（从 @aiao/rxdb-adapter-sqlite-core 再导出）
适配器主体 RxDBAdapterSqlite
客户端 SqliteClient，负责 SQLite 连接、变更拦截与批量派发
加载工具 sqliteLoad：按 VFS 选型懒加载 sqlite-wasm 产物

Classes

Class	Description
RxDBAdapterSqlite	浏览器 @subframe7536/sqlite-wasm 适配器。
RxDBAdapterSqliteError	RxDB SQLite 适配器错误类
SqliteClient	类型安全的同步事件调度器。
SqliteRepository	操作实体仓库

Interfaces

Interface	Description
GenerateSqlResult	SQL 生成结果：完整的 SQL 语句与可选的参数绑定。
RxDBAdapterSqliteBase	与后端无关的 SQLite adapter 基类。
SqliteOptions	SQLite 适配器配置接口

Type Aliases

Type Alias	Description
SupportVFS	支持的 @subframe7536/sqlite-wasm 存储预设

Variables

Variable	Description
buildRuleGroup	生成 ruleGroup sql 查询条件
ROWID	sqlite 行 id 列名
SQLITE_WASM_VFS_LIST	-
sqliteGetTableName	获取表名
sqliteGetTableNameByMetadata	通过元数据获取表名

Functions

Function	Description
createSqliteClient	-
releaseComlinkProxy	释放 Comlink 代理占用的 MessagePort。
sqliteLoad	加载并初始化 @subframe7536/sqlite-wasm

何时使用​

与其他 SQLite 适配器对比​

支持的存储（VFS 预设）​

安装​

用法​

备份与恢复​

完整示例​

Fileoverview​

Classes​

Interfaces​

Type Aliases​

Variables​

Functions​