@aiao/rxdb-adapter-sqliteai 0.0.23 → 0.0.24

package/README.md

@@ -0,0 +1,31 @@
+# @aiao/rxdb-adapter-sqliteai
+
+`@aiao/rxdb` 的 [sqliteai](https://github.com/sqliteai) 存储适配器，为核心引擎提供基于 sqliteai 运行时的 SQLite 后端。
+
+## 安装
+
+```bash
+pnpm add @aiao/rxdb @aiao/rxdb-adapter-sqliteai rxjs
+```
+
+## 用法
+
+```typescript
+import { createSqliteClient, RxDBAdapterSqliteai, sqliteaiLoad } from '@aiao/rxdb-adapter-sqliteai';
+```
+
+- `RxDBAdapterSqliteai`：接入 `@aiao/rxdb` 的适配器实现
+- `createSqliteClient` / `SqliteaiClient`：sqliteai 客户端
+- `sqliteaiLoad`：运行时加载
+- 类型：`SqliteaiOptions`
+
+适配器共享内核（表名解析、规则编译、基础 Repository）来自 [`@aiao/rxdb-adapter-sqlite-core`](../rxdb-adapter-sqlite-core)。
+
+## 文档
+
+- 仓库主页：[https://github.com/aiao-io/aiao](https://github.com/aiao-io/aiao)
+- 适配器与存储后端指南见项目文档站
+
+## License
+
+[MIT](https://github.com/aiao-io/aiao/blob/main/LICENSE)

package/dist/create_sqlite_client.d.ts

@@ -1,14 +1,19 @@
+import { SqliteClientLike } from '@aiao/rxdb-adapter-sqlite-core';
 import { SqliteaiOptions } from './sqliteai.interface.js';
-import { SqliteaiClient } from './SqliteaiClient.js';
 /**
  * 创建 SqliteAI 客户端实例并完成初始化。
  *
  * 如果 `options` 中指定了 worker / sharedWorker，会通过 `wrapWithComlink` 把客户端代理到 worker；
  * 否则在主线程直接 new。
  *
+ * 返回类型是 {@link SqliteClientLike} 而非具体的 `SqliteaiClient`：worker 模式下拿到的是
+ * Comlink 远端代理，它把每个方法都 Promise 化，断言成实现类会让 `beginTransactionSql(): string`
+ * 这类同步签名在跨线程模式下变成谎报（SQLC-040）。
+ *
  * @param dbName - 数据库名（用于持久化文件名归一化）
  * @param options - SqliteAI 适配器选项（含 OPFS / worker / 缓存大小等）
- * @returns 已 `init` 完成、可直接执行 SQL 的客户端
+ * @returns 已 `init` 完成、可直接执行 SQL 的客户端（主线程实例或其远端代理）
+ * @throws worker / sharedWorker 模式下传入 `locateFile` / `print` / `printErr` 等函数型选项时抛错
  */
-export declare function createSqliteClient(dbName: string, options: SqliteaiOptions): Promise<SqliteaiClient>;
+export declare function createSqliteClient(dbName: string, options: SqliteaiOptions): Promise<SqliteClientLike>;
 //# sourceMappingURL=create_sqlite_client.d.ts.map

package/dist/create_sqlite_client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create_sqlite_client.d.ts","sourceRoot":"","sources":["../src/create_sqlite_client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAA4B,MAAM,yBAAyB,CAAC;AACpF,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAgB1G"}
+{"version":3,"file":"create_sqlite_client.d.ts","sourceRoot":"","sources":["../src/create_sqlite_client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkD,KAAK,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AACvH,OAAO,EAAE,eAAe,EAA4B,MAAM,yBAAyB,CAAC;AAGpF;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAkB5G"}

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-export { ROWID, RxDBAdapterSqliteError, SqliteRepository, buildRuleGroup, get_table_name as sqliteGetTableName, get_table_name_by_metadata as sqliteGetTableNameByMetadata } from '@aiao/rxdb-adapter-sqlite-core';
+export { BATCH_TIMEOUT, ROWID, RxDBAdapterSqliteError, SqliteRepository, buildRuleGroup, get_table_name as sqliteGetTableName, get_table_name_by_metadata as sqliteGetTableNameByMetadata } from '@aiao/rxdb-adapter-sqlite-core';
 export type { GenerateSqlResult } from '@aiao/rxdb-adapter-sqlite-core';
 export { createSqliteClient } from './create_sqlite_client.js';
 export { RxDBAdapterSqliteai } from './RxDBAdapterSqliteai.js';
 export { sqliteaiLoad } from './sqliteai-load.utils.js';
-export type { SqliteaiOptions } from './sqliteai.interface.js';
+export type { SqliteaiLoadOptions, SqliteaiOptions, SqliteaiRepositoryConstructor } from './sqliteai.interface.js';
 export { SqliteaiClient } from './SqliteaiClient.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,EACL,sBAAsB,EACtB,gBAAgB,EAChB,cAAc,EACd,cAAc,IAAI,kBAAkB,EACpC,0BAA0B,IAAI,4BAA4B,EAC3D,MAAM,gCAAgC,CAAC;AACxC,YAAY,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAGxE,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,YAAY,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,aAAa,EACb,KAAK,EACL,sBAAsB,EACtB,gBAAgB,EAChB,cAAc,EACd,cAAc,IAAI,kBAAkB,EACpC,0BAA0B,IAAI,4BAA4B,EAC3D,MAAM,gCAAgC,CAAC;AACxC,YAAY,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAGxE,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,YAAY,EAAE,mBAAmB,EAAE,eAAe,EAAE,6BAA6B,EAAE,MAAM,yBAAyB,CAAC;AACnH,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -1,29 +1,32 @@
-import { Oo1ClientBase as e, ROWID as t, RxDBAdapterSqliteBase as n, RxDBAdapterSqliteError as r, SqliteRepository as i, buildOo1InitOptions as a, buildRuleGroup as o, defaultWarn as s, get_table_name as c, get_table_name_by_metadata as l, withGlobalOo1LoadLock as u, withPatchedOpfsProxyWorker as d, withSqliteApiConfig as f, wrapWithComlink as p } from "@aiao/rxdb-adapter-sqlite-core";
-import m from "@sqliteai/sqlite-wasm";
+import { BATCH_TIMEOUT as e, Oo1ClientBase as t, ROWID as n, RxDBAdapterSqliteBase as r, RxDBAdapterSqliteError as i, SqliteRepository as a, assertLoadOptionsTransferable as o, assertOo1Static as s, buildOo1InitOptions as c, buildRuleGroup as l, defaultWarn as u, get_table_name as d, get_table_name_by_metadata as f, isSameOo1LoadConfig as p, toOo1LoadFingerprint as m, withGlobalOo1LoadLock as h, withPatchedOpfsProxyWorker as g, withSqliteApiConfig as _, wrapWithComlink as v } from "@aiao/rxdb-adapter-sqlite-core";
+import y from "@sqliteai/sqlite-wasm";
 //#region src/sqliteai-load.utils.ts
-var h, g = !1;
-async function _(e) {
-	let t = !!e?.opfs && !!e.opfsProxyPath, n = () => h && (!t || g) ? h : void 0;
-	return n() || u(async () => {
+var b, x;
+async function S(e) {
+	let t = m(e), n = () => b && x && p(x, t) ? b : void 0;
+	return n() || h(async () => {
 		let r = n();
 		if (r) return r;
-		let i = a(e), o = await d(e, async () => await f({ warn: s }, async () => await m(i)));
-		return o.config && (o.config.warn = s), h = o, g = t, o;
+		let i = c(e), a = await g(e, async () => await _({ warn: u }, async () => {
+			let e = await y(i);
+			return s(e), e;
+		}));
+		return a.config && (a.config.warn = u), b = a, x = t, a;
 	});
 }
 //#endregion
 //#region src/SqliteaiClient.ts
-var v = class extends e {
+var C = class extends t {
 	get clientName() {
 		return "sqliteai";
 	}
 	loadModule(e) {
-		return _(e);
+		return S(e);
 	}
 };
 //#endregion
 //#region src/create_sqlite_client.ts
-async function y(e, t) {
+async function w(e, t) {
 	let n = {
 		opfs: t.opfs,
 		wasmPath: t.wasmPath,
@@ -34,21 +37,23 @@ async function y(e, t) {
 		cacheSizeKb: t.cacheSizeKb,
 		batchTimeout: t.batchTimeout,
 		opfsFallback: t.opfsFallback
-	}, r = p(new v(), t);
+	};
+	o(n, t);
+	let r = v(new C(), t);
 	return await r.init(e, n), r;
 }
 //#endregion
 //#region src/sqliteai.interface.ts
-var b = "sqliteai", x = class extends n {
+var T = "sqliteai", E = class extends r {
 	options;
 	#e;
-	name = b;
+	name = T;
 	constructor(e, t) {
 		super(e, t), this.options = t, this.#e = e.config.dbName;
 	}
 	async createClient() {
-		return y(this.#e, this.options);
+		return w(this.#e, this.options);
 	}
 };
 //#endregion
-export { t as ROWID, r as RxDBAdapterSqliteError, x as RxDBAdapterSqliteai, i as SqliteRepository, v as SqliteaiClient, o as buildRuleGroup, y as createSqliteClient, c as sqliteGetTableName, l as sqliteGetTableNameByMetadata, _ as sqliteaiLoad };
+export { e as BATCH_TIMEOUT, n as ROWID, i as RxDBAdapterSqliteError, E as RxDBAdapterSqliteai, a as SqliteRepository, C as SqliteaiClient, l as buildRuleGroup, w as createSqliteClient, d as sqliteGetTableName, f as sqliteGetTableNameByMetadata, S as sqliteaiLoad };

package/dist/sqliteai-load.utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sqliteai-load.utils.d.ts","sourceRoot":"","sources":["../src/sqliteai-load.utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,SAAS,EAIf,MAAM,gCAAgC,CAAC;AAExC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAKnE;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAG7C;AAED;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,SAAS,CAAC,CA6BpF"}
+{"version":3,"file":"sqliteai-load.utils.d.ts","sourceRoot":"","sources":["../src/sqliteai-load.utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAUL,KAAK,SAAS,EACf,MAAM,gCAAgC,CAAC;AAExC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAYnE;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAG7C;AAED;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,SAAS,CAAC,CAkCpF"}

package/dist/sqliteai.interface.d.ts

@@ -17,9 +17,9 @@ interface SqliteaiOptionsBase extends IRxDBAdapterOptions {
     printErr?: (msg: string) => void;
     /** @see https://www.sqlite.org/pragma.html#pragma_cache_size @default 51200 */
     cacheSizeKb?: number;
-    /** @default 16 (BALANCED) @see BATCH_TIMEOUT */
+    /** @default 16（BALANCED）@see BATCH_TIMEOUT */
     batchTimeout?: number;
-    /** Behaviour when OPFS database opening fails. @default 'memory' */
+    /** OPFS 数据库打开失败时的行为。@default 'throw' @see Oo1ClientBase */
     opfsFallback?: OpfsFallback;
     worker?: boolean;
     workerInstance?: Worker;

package/dist/sqliteai.interface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sqliteai.interface.d.ts","sourceRoot":"","sources":["../src/sqliteai.interface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC3F,OAAO,KAAK,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAE1F;;;;;;;GAOG;AACH,UAAU,mBAAoB,SAAQ,mBAAmB;IACvD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACtC,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,oBAAoB,CAAC,EAAE,YAAY,CAAC;CACrC;AAED,eAAe;AACf,KAAK,aAAa,GAAG,UAAU,GAAG,CAAC,KAAK,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC,CAAC;AAEtE,mEAAmE;AACnE,MAAM,MAAM,6BAA6B,CAAC,CAAC,SAAS,cAAc,CAAC,aAAa,CAAC,IAAI,KACnF,OAAO,EAAE,qBAAqB,EAC9B,UAAU,EAAE,UAAU,KACnB,CAAC,CAAC;AAEP,gDAAgD;AAChD,MAAM,WAAW,eAAgB,SAAQ,mBAAmB;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,6BAA6B,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;CAC7F;AAED,4DAA4D;AAC5D,MAAM,MAAM,mBAAmB,GAAG,IAAI,CACpC,mBAAmB,EACjB,MAAM,GACN,UAAU,GACV,eAAe,GACf,YAAY,GACZ,OAAO,GACP,UAAU,GACV,aAAa,GACb,cAAc,GACd,cAAc,CACjB,CAAC;AAEF,2BAA2B;AAC3B,eAAO,MAAM,YAAY,EAAG,UAAmB,CAAC"}
+{"version":3,"file":"sqliteai.interface.d.ts","sourceRoot":"","sources":["../src/sqliteai.interface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC3F,OAAO,KAAK,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAE1F;;;;;;;GAOG;AACH,UAAU,mBAAoB,SAAQ,mBAAmB;IACvD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACtC,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,oBAAoB,CAAC,EAAE,YAAY,CAAC;CACrC;AAED,eAAe;AACf,KAAK,aAAa,GAAG,UAAU,GAAG,CAAC,KAAK,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC,CAAC;AAEtE,mEAAmE;AACnE,MAAM,MAAM,6BAA6B,CAAC,CAAC,SAAS,cAAc,CAAC,aAAa,CAAC,IAAI,KACnF,OAAO,EAAE,qBAAqB,EAC9B,UAAU,EAAE,UAAU,KACnB,CAAC,CAAC;AAEP,gDAAgD;AAChD,MAAM,WAAW,eAAgB,SAAQ,mBAAmB;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,6BAA6B,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;CAC7F;AAED,4DAA4D;AAC5D,MAAM,MAAM,mBAAmB,GAAG,IAAI,CACpC,mBAAmB,EACjB,MAAM,GACN,UAAU,GACV,eAAe,GACf,YAAY,GACZ,OAAO,GACP,UAAU,GACV,aAAa,GACb,cAAc,GACd,cAAc,CACjB,CAAC;AAEF,2BAA2B;AAC3B,eAAO,MAAM,YAAY,EAAG,UAAmB,CAAC"}

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@aiao/rxdb-adapter-sqliteai",
-  "version": "0.0.23",
+  "version": "0.0.24",
+  "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -8,7 +9,6 @@
   "exports": {
     "./package.json": "./package.json",
     ".": {
-      "@aiao/source": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
@@ -16,6 +16,10 @@
   },
   "files": [
     "dist",
+    "src",
+    "!src/**/*.spec.*",
+    "!src/**/*.test.*",
+    "!src/**/__tests__/**",
     "!**/*.tsbuildinfo"
   ],
   "publishConfig": {
@@ -29,11 +33,12 @@
   },
   "dependencies": {
     "@sqliteai/sqlite-wasm": "3.50.4-wasm.1.0.0-sync.1.1.2-vector.1.0.0-memory.1.3.5",
-    "@aiao/rxdb-adapter-sqlite-core": "0.0.23",
-    "@aiao/rxdb": "0.0.23"
+    "@aiao/rxdb": "0.0.24",
+    "@aiao/rxdb-adapter-sqlite-core": "0.0.24"
   },
   "devDependencies": {
+    "comlink": "^4.4.2",
     "ms": "^2.1.3",
-    "@aiao/rxdb-test": "0.0.23"
+    "@aiao/rxdb-test": "0.0.24"
   }
 }

package/src/RxDBAdapterSqliteai.ts

@@ -0,0 +1,34 @@
+import type { RxDB } from '@aiao/rxdb';
+import { RxDBAdapterSqliteBase, type SqliteClientLike } from '@aiao/rxdb-adapter-sqlite-core';
+import { createSqliteClient } from './create_sqlite_client.js';
+import { ADAPTER_NAME, type SqliteaiOptions } from './sqliteai.interface.js';
+
+/**
+ * 基于 `@sqliteai/sqlite-wasm` 的 RxDB 本地存储适配器。
+ *
+ * 与 `rxdb-adapter-sqlite`（官方 sqlite-wasm 绑定）API 对齐，差异：
+ * - WASM 二进制来自 SqliteAI 的发行版（OPFS / Worker 配置一致）
+ * - 客户端实现继承 `Oo1ClientBase`，复用 sqlite-core 的队列与事件批处理
+ */
+export class RxDBAdapterSqliteai extends RxDBAdapterSqliteBase {
+  readonly #dbName: string;
+  override readonly name: string = ADAPTER_NAME;
+
+  constructor(
+    rxdb: RxDB,
+    readonly options: SqliteaiOptions
+  ) {
+    super(rxdb, options);
+    this.#dbName = rxdb.config.dbName;
+  }
+
+  protected override async createClient(): Promise<SqliteClientLike> {
+    return createSqliteClient(this.#dbName, this.options);
+  }
+}
+
+declare module '@aiao/rxdb' {
+  interface RxDBAdapters {
+    [ADAPTER_NAME]: RxDBAdapterSqliteai;
+  }
+}

package/src/SqliteaiClient.ts

@@ -0,0 +1,21 @@
+import { BATCH_TIMEOUT, Oo1ClientBase, type Oo1Static } from '@aiao/rxdb-adapter-sqlite-core';
+import { sqliteaiLoad } from './sqliteai-load.utils.js';
+import type { SqliteaiLoadOptions } from './sqliteai.interface.js';
+
+export { BATCH_TIMEOUT };
+
+/**
+ * SqliteAI 的 oo1 客户端实现。
+ *
+ * 仅声明 `clientName` 与 `loadModule`，其余生命周期（init / disconnect / 事件批处理 /
+ * 队列 / 自定义函数注册 / OPFS fallback）全部由 `Oo1ClientBase` 提供。
+ */
+export class SqliteaiClient extends Oo1ClientBase<SqliteaiLoadOptions> {
+  protected get clientName(): string {
+    return 'sqliteai';
+  }
+
+  protected loadModule(options?: SqliteaiLoadOptions): Promise<Oo1Static> {
+    return sqliteaiLoad(options);
+  }
+}

package/src/create_sqlite_client.ts

@@ -0,0 +1,38 @@
+import { assertLoadOptionsTransferable, wrapWithComlink, type SqliteClientLike } from '@aiao/rxdb-adapter-sqlite-core';
+import { SqliteaiOptions, type SqliteaiLoadOptions } from './sqliteai.interface.js';
+import { SqliteaiClient } from './SqliteaiClient.js';
+
+/**
+ * 创建 SqliteAI 客户端实例并完成初始化。
+ *
+ * 如果 `options` 中指定了 worker / sharedWorker，会通过 `wrapWithComlink` 把客户端代理到 worker；
+ * 否则在主线程直接 new。
+ *
+ * 返回类型是 {@link SqliteClientLike} 而非具体的 `SqliteaiClient`：worker 模式下拿到的是
+ * Comlink 远端代理，它把每个方法都 Promise 化，断言成实现类会让 `beginTransactionSql(): string`
+ * 这类同步签名在跨线程模式下变成谎报（SQLC-040）。
+ *
+ * @param dbName - 数据库名（用于持久化文件名归一化）
+ * @param options - SqliteAI 适配器选项（含 OPFS / worker / 缓存大小等）
+ * @returns 已 `init` 完成、可直接执行 SQL 的客户端（主线程实例或其远端代理）
+ * @throws worker / sharedWorker 模式下传入 `locateFile` / `print` / `printErr` 等函数型选项时抛错
+ */
+export async function createSqliteClient(dbName: string, options: SqliteaiOptions): Promise<SqliteClientLike> {
+  const loadOptions: SqliteaiLoadOptions = {
+    opfs: options.opfs,
+    wasmPath: options.wasmPath,
+    opfsProxyPath: options.opfsProxyPath,
+    locateFile: options.locateFile,
+    print: options.print,
+    printErr: options.printErr,
+    cacheSizeKb: options.cacheSizeKb,
+    batchTimeout: options.batchTimeout,
+    opfsFallback: options.opfsFallback
+  };
+
+  assertLoadOptionsTransferable(loadOptions, options);
+
+  const client = wrapWithComlink(new SqliteaiClient(), options);
+  await client.init(dbName, loadOptions);
+  return client;
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+// 从 core 重新导出共享类型和函数。
+export {
+  BATCH_TIMEOUT,
+  ROWID,
+  RxDBAdapterSqliteError,
+  SqliteRepository,
+  buildRuleGroup,
+  get_table_name as sqliteGetTableName,
+  get_table_name_by_metadata as sqliteGetTableNameByMetadata
+} from '@aiao/rxdb-adapter-sqlite-core';
+export type { GenerateSqlResult } from '@aiao/rxdb-adapter-sqlite-core';
+
+// sqliteai 专用导出。
+export { createSqliteClient } from './create_sqlite_client.js';
+export { RxDBAdapterSqliteai } from './RxDBAdapterSqliteai.js';
+export { sqliteaiLoad } from './sqliteai-load.utils.js';
+export type { SqliteaiLoadOptions, SqliteaiOptions, SqliteaiRepositoryConstructor } from './sqliteai.interface.js';
+export { SqliteaiClient } from './SqliteaiClient.js';

package/src/sqliteai-load.utils.ts

@@ -0,0 +1,80 @@
+import {
+  assertOo1Static,
+  buildOo1InitOptions,
+  defaultWarn,
+  isSameOo1LoadConfig,
+  toOo1LoadFingerprint,
+  withGlobalOo1LoadLock,
+  withPatchedOpfsProxyWorker,
+  withSqliteApiConfig,
+  type Oo1LoadFingerprint,
+  type Oo1Static
+} from '@aiao/rxdb-adapter-sqlite-core';
+import sqlite3InitModule from '@sqliteai/sqlite-wasm';
+import type { SqliteaiLoadOptions } from './sqliteai.interface.js';
+
+let cachedModule: Oo1Static | undefined;
+/**
+ * 缓存模块对应的加载指纹。
+ *
+ * @remarks
+ * SQLAI-001：早先只记一个布尔「是否用过 OPFS proxy patch」，
+ * 于是不同 `wasmPath` / `opfsProxyPath` / `locateFile` 的后续调用会静默拿到首个模块。
+ */
+let cachedFingerprint: Oo1LoadFingerprint | undefined;
+
+/**
+ * 清除模块级 SqliteAI WASM 缓存。
+ *
+ * 仅供测试使用：每个测试用例需要重新加载干净模块时调用，
+ * 生产代码不应依赖这个钩子。
+ */
+export function resetSqliteaiLoadCache(): void {
+  cachedModule = undefined;
+  cachedFingerprint = undefined;
+}
+
+/**
+ * 加载 SqliteAI WASM 模块（带模块级缓存）。
+ *
+ * 第一次调用会下载并初始化 WASM；之后调用复用缓存的 `Oo1Static`。
+ * 若新调用需要 OPFS proxy patch 而缓存模块未启用过，会重新加载一次以应用 patch。
+ *
+ * @param options - 加载选项（含 OPFS / wasmPath / printErr 等）
+ * @returns 共享的 `Oo1Static` 实例
+ */
+export async function sqliteaiLoad(options?: SqliteaiLoadOptions): Promise<Oo1Static> {
+  const fingerprint = toOo1LoadFingerprint(options);
+  // 只有「决定加载什么」的配置完全一致才复用缓存；否则重新加载。
+  // 早先的缓存键只有一个布尔（是否用过 OPFS proxy patch），
+  // 不同 wasmPath / opfsProxyPath / locateFile 会静默拿到首个模块。
+  const cacheHit = (): Oo1Static | undefined =>
+    cachedModule && cachedFingerprint && isSameOo1LoadConfig(cachedFingerprint, fingerprint) ? cachedModule : undefined;
+
+  const hit = cacheHit();
+  if (hit) {
+    return hit;
+  }
+
+  return withGlobalOo1LoadLock(async () => {
+    const lockedHit = cacheHit();
+    if (lockedHit) {
+      return lockedHit;
+    }
+
+    const initOptions = buildOo1InitOptions(options);
+    const module = await withPatchedOpfsProxyWorker(options, async () => {
+      return await withSqliteApiConfig({ warn: defaultWarn }, async () => {
+        const loadedModule: unknown = await sqlite3InitModule(initOptions);
+        assertOo1Static(loadedModule);
+        return loadedModule;
+      });
+    });
+    if (module.config) {
+      module.config.warn = defaultWarn;
+    }
+    cachedModule = module;
+    cachedFingerprint = fingerprint;
+    return module;
+  });
+}

package/src/sqliteai.interface.ts

@@ -0,0 +1,60 @@
+import type { EntityType, IEntity, IRxDBAdapterOptions, RepositoryBase } from '@aiao/rxdb';
+import type { OpfsFallback, RxDBAdapterSqliteBase } from '@aiao/rxdb-adapter-sqlite-core';
+
+/**
+ * SqliteAI 适配器的可配置项（不含自定义 repository 注册）。
+ *
+ * - `opfs` / `opfsProxyPath` / `opfsFallback`：OPFS 持久化相关
+ * - `wasmPath` / `locateFile`：WASM 资源定位
+ * - `worker` / `sharedWorker` + `*Instance`：跨线程运行
+ * - `cacheSizeKb` / `batchTimeout`：性能调优
+ */
+interface SqliteaiOptionsBase extends IRxDBAdapterOptions {
+  opfs?: boolean;
+  wasmPath?: string;
+  opfsProxyPath?: string;
+  locateFile?: (name: string) => string;
+  print?: (msg: string) => void;
+  printErr?: (msg: string) => void;
+  /** @see https://www.sqlite.org/pragma.html#pragma_cache_size @default 51200 */
+  cacheSizeKb?: number;
+  /** @default 16（BALANCED）@see BATCH_TIMEOUT */
+  batchTimeout?: number;
+  /** OPFS 数据库打开失败时的行为。@default 'throw' @see Oo1ClientBase */
+  opfsFallback?: OpfsFallback;
+  worker?: boolean;
+  workerInstance?: Worker;
+  sharedWorker?: boolean;
+  sharedWorkerInstance?: SharedWorker;
+}
+
+/** 任意实体构造器。 */
+type AnyEntityType = EntityType & (new (...args: never[]) => IEntity);
+
+/** 自定义 Repository 类的构造器签名（用户可覆盖默认 Repository / TreeRepository）。 */
+export type SqliteaiRepositoryConstructor<T extends RepositoryBase<AnyEntityType>> = new (
+  adapter: RxDBAdapterSqliteBase,
+  EntityType: EntityType
+) => T;
+
+/** SqliteAI 适配器完整选项（含可选的自定义 Repository 注册表）。 */
+export interface SqliteaiOptions extends SqliteaiOptionsBase {
+  repositories?: Record<string, SqliteaiRepositoryConstructor<RepositoryBase<AnyEntityType>>>;
+}
+
+/** `sqliteaiLoad` 接受的运行期选项子集（剥离 worker / repository 配置）。 */
+export type SqliteaiLoadOptions = Pick<
+  SqliteaiOptionsBase,
+  | 'opfs'
+  | 'wasmPath'
+  | 'opfsProxyPath'
+  | 'locateFile'
+  | 'print'
+  | 'printErr'
+  | 'cacheSizeKb'
+  | 'batchTimeout'
+  | 'opfsFallback'
+>;
+
+/** 在 RxDB 中注册此适配器使用的名称。 */
+export const ADAPTER_NAME = 'sqliteai' as const;