@aiao/rxdb-adapter-electron 0.0.0-stage → 0.0.26

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `@aiao/rxdb-adapter-electron` 的 **renderer 侧**入口。
+ *
+ * @remarks
+ * 本入口只含跨传输层说话所需的东西，**不引用 `node:sqlite`**，因此可以安全地打进
+ * 浏览器上下文的 renderer bundle。特权侧（Electron 主进程或它拥有的 worker）请改用
+ * `@aiao/rxdb-adapter-electron/host`。
+ *
+ * 协议、renderer client、存储联合与错误类型的**实现**已下沉到
+ * `@aiao/rxdb-adapter-sqlite-core/desktop-host`（US-207 E1），两个桌面运行时共用一份。
+ * 本入口原样转出它们：下游按名字 import，实现搬到哪个包不该让用户改行。
+ *
+ * @module @aiao/rxdb-adapter-electron
+ */
+export { ADAPTER_NAME as ELECTRON_ADAPTER_NAME } from './electron-adapter.interface.js';
+export { RxDBAdapterElectron } from './RxDBAdapterElectron.js';
+export { DEFAULT_DATABASE_SUFFIX as DESKTOP_DEFAULT_DATABASE_SUFFIX, type DesktopOptions } from '@aiao/rxdb-adapter-sqlite-core/desktop-host';
+export { RxDBAdapterDesktopError, type RxDBAdapterDesktopErrorCode } from '@aiao/rxdb-adapter-sqlite-core/desktop-host';
+export { DESKTOP_HOST_TRANSPORT_KEY, DesktopSqliteClient, resolveDesktopHostTransport, type DesktopHostTransport, type DesktopSqliteClientOptions } from '@aiao/rxdb-adapter-sqlite-core/desktop-host';
+export { assertDesktopSqliteStorage, assertValidDesktopDatabaseName, isDesktopPgliteDirectoryStorage, isDesktopSqliteFileStorage, type DesktopPgliteDirectoryStorage, type DesktopSqliteFileStorage, type DesktopStorage } from '@aiao/rxdb-adapter-sqlite-core/desktop-host';
+export { DESKTOP_HOST_MAX_BINDINGS, DESKTOP_HOST_MAX_BLOB_BYTES, DESKTOP_HOST_MAX_FILE_CHUNK_BYTES, DESKTOP_HOST_MAX_SQL_LENGTH, DESKTOP_HOST_PROTOCOL_VERSION, assertDesktopHostResponse, parseDesktopHostChangeEvent, parseDesktopHostHandshakeResult, parseDesktopHostOpenResult, type DesktopHostChangeEventMessage, type DesktopHostCloseRequest, type DesktopHostExecuteRequest, type DesktopHostFileEntry, type DesktopHostFileLockMode, type DesktopHostFileReadResult, type DesktopHostFileRequest, type DesktopHostFileResponse, type DesktopHostFileStat, type DesktopHostHandshakeRequest, type DesktopHostHandshakeResult, type DesktopHostOpenRequest, type DesktopHostOpenResult, type DesktopHostRequest, type DesktopHostResponse, type DesktopHostVersionRequest } from '@aiao/rxdb-adapter-sqlite-core/desktop-host';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,YAAY,IAAI,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AACxF,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAE/D,OAAO,EACL,uBAAuB,IAAI,+BAA+B,EAC1D,KAAK,cAAc,EACpB,MAAM,6CAA6C,CAAC;AAErD,OAAO,EAAE,uBAAuB,EAAE,KAAK,2BAA2B,EAAE,MAAM,6CAA6C,CAAC;AAExH,OAAO,EACL,0BAA0B,EAC1B,mBAAmB,EACnB,2BAA2B,EAC3B,KAAK,oBAAoB,EACzB,KAAK,0BAA0B,EAChC,MAAM,6CAA6C,CAAC;AAErD,OAAO,EACL,0BAA0B,EAC1B,8BAA8B,EAC9B,+BAA+B,EAC/B,0BAA0B,EAC1B,KAAK,6BAA6B,EAClC,KAAK,wBAAwB,EAC7B,KAAK,cAAc,EACpB,MAAM,6CAA6C,CAAC;AAErD,OAAO,EACL,yBAAyB,EACzB,2BAA2B,EAC3B,iCAAiC,EACjC,2BAA2B,EAC3B,6BAA6B,EAC7B,yBAAyB,EACzB,2BAA2B,EAC3B,+BAA+B,EAC/B,0BAA0B,EAC1B,KAAK,6BAA6B,EAClC,KAAK,uBAAuB,EAC5B,KAAK,yBAAyB,EAC9B,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,yBAAyB,EAC9B,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,EAC/B,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC/B,MAAM,6CAA6C,CAAC"}

package/dist/index.js

@@ -0,0 +1,22 @@
+import { RxDBAdapterSqliteBase as e } from "@aiao/rxdb-adapter-sqlite-core";
+import { DEFAULT_DATABASE_SUFFIX as t, DEFAULT_DATABASE_SUFFIX as n, DESKTOP_HOST_MAX_BINDINGS as r, DESKTOP_HOST_MAX_BLOB_BYTES as i, DESKTOP_HOST_MAX_FILE_CHUNK_BYTES as a, DESKTOP_HOST_MAX_SQL_LENGTH as o, DESKTOP_HOST_PROTOCOL_VERSION as s, DESKTOP_HOST_TRANSPORT_KEY as c, DesktopSqliteClient as l, DesktopSqliteClient as u, RxDBAdapterDesktopError as d, assertDesktopHostResponse as f, assertDesktopSqliteStorage as p, assertValidDesktopDatabaseName as m, assertValidDesktopDatabaseName as h, isDesktopPgliteDirectoryStorage as g, isDesktopSqliteFileStorage as _, parseDesktopHostChangeEvent as v, parseDesktopHostHandshakeResult as y, parseDesktopHostOpenResult as b, resolveDesktopHostTransport as x, resolveDesktopHostTransport as S } from "@aiao/rxdb-adapter-sqlite-core/desktop-host";
+//#region src/electron-adapter.interface.ts
+var C = "sqlite-electron", w = class extends e {
+	options;
+	#e;
+	name = C;
+	get databaseName() {
+		return this.#e;
+	}
+	constructor(e, n = {}) {
+		super(e, n), this.options = n, this.#e = n.databaseName ?? `${e.config.dbName}${t}`, h(this.#e);
+	}
+	async createClient() {
+		return u.connect(this.options.transport ?? S(), {
+			engine: "sqlite",
+			databaseName: this.#e
+		}, { batchTimeout: this.options.batchTimeout });
+	}
+};
+//#endregion
+export { n as DESKTOP_DEFAULT_DATABASE_SUFFIX, r as DESKTOP_HOST_MAX_BINDINGS, i as DESKTOP_HOST_MAX_BLOB_BYTES, a as DESKTOP_HOST_MAX_FILE_CHUNK_BYTES, o as DESKTOP_HOST_MAX_SQL_LENGTH, s as DESKTOP_HOST_PROTOCOL_VERSION, c as DESKTOP_HOST_TRANSPORT_KEY, l as DesktopSqliteClient, C as ELECTRON_ADAPTER_NAME, d as RxDBAdapterDesktopError, w as RxDBAdapterElectron, f as assertDesktopHostResponse, p as assertDesktopSqliteStorage, m as assertValidDesktopDatabaseName, g as isDesktopPgliteDirectoryStorage, _ as isDesktopSqliteFileStorage, v as parseDesktopHostChangeEvent, y as parseDesktopHostHandshakeResult, b as parseDesktopHostOpenResult, x as resolveDesktopHostTransport };

package/dist/node-sqlite-engine.d.ts

@@ -0,0 +1,87 @@
+import { SqliteChangeEvent, SQLiteCompatibleType, SqliteResult } from '@aiao/rxdb-adapter-sqlite-core';
+/** {@link NodeSqliteEngine.open} 的入参。 */
+export interface NodeSqliteEngineOptions {
+    /** 数据库文件的绝对物理路径，由 host 在应用数据目录内解析得出。 */
+    readonly filePath: string;
+    /** 逻辑数据库名，仅用于变更事件的诊断字段。 */
+    readonly dbName: string;
+    /**
+     * 变更事件回调。
+     *
+     * @remarks
+     * 在产生变更的语句返回**之后**的任务里调用（批处理见 {@link NodeSqliteEngineOptions.batchTimeout}），
+     * 唯一的例外是 {@link NodeSqliteEngine.close} 里的收尾 flush。实现方不该抛错——
+     * 此刻写入早已落库，没有任何调用方还能对失败做出反应；真抛了也只会被隔离并 log，
+     * 既不会中断同批次的其余分组，也不会传播给写入方。
+     */
+    readonly onChange: (event: SqliteChangeEvent) => void;
+    /** SQLite page cache 大小（KB），默认 {@link DEFAULT_CACHE_SIZE_KB}。 */
+    readonly cacheSizeKb?: number;
+    /**
+     * 变更事件的防抖窗口（毫秒），默认 {@link DEFAULT_BATCH_TIMEOUT}。
+     *
+     * @remarks
+     * 与 wasm 后端的同名选项同义：窗口内的连续写入合并成一次派发。0 表示下一个宏任务立即派发。
+     */
+    readonly batchTimeout?: number;
+}
+/**
+ * 单个数据库连接。
+ *
+ * @remarks
+ * 一个会话一个连接，不共享：两个窗口若共用一条连接，它们的 `BEGIN` 块会互相穿插，
+ * 事务隔离直接失效。各自持有连接后，跨窗口的并发交给 SQLite 自己的文件锁与写者租约处理。
+ */
+export declare class NodeSqliteEngine {
+    #private;
+    private constructor();
+    /**
+     * 打开（必要时创建）一个数据库文件。
+     *
+     * @remarks
+     * 打不开就抛错，**绝不**回退到内存库或另一个位置：用户必须能确信数据确实写进了
+     * 他指定的那个文件（AC#4）。初始化中途失败时会把已开的句柄关掉，不留悬挂连接。
+     *
+     * @param options - 引擎配置
+     * @returns 已完成初始化、已装好变更通知的引擎
+     * @throws {@link RxDBAdapterDesktopError} code 为 `open_failed` / `permission_denied` / `database_corrupted`
+     */
+    static open(options: NodeSqliteEngineOptions): NodeSqliteEngine;
+    /**
+     * 执行一条或一组 SQL。
+     *
+     * @remarks
+     * 结果形状与 `executeOo1Helper` 逐字对齐（AC#2）：至多一个结果集，且只在语句真的产出列时才有；
+     * 只读语句的 `rowsAffected` 恒为 0，不泄漏上一条写语句遗留的计数。
+     *
+     * 多语句脚本逐条 prepare 执行（切分见 {@link splitSqliteScript}），但**不接受绑定参数**：
+     * 参数属于其中某一条语句，静默绑到第一条只会把数据写错位；wasm 后端同样拒绝这个组合。
+     *
+     * @param sql - 待执行的 SQL
+     * @param bindings - 位置绑定参数
+     * @returns 与 sqlite 核心一致的执行结果
+     * @throws {@link RxDBAdapterDesktopError} 会话已关闭、多语句带参、或 SQL 执行失败时
+     */
+    execute(sql: string, bindings?: readonly SQLiteCompatibleType[]): SqliteResult;
+    /**
+     * 报告底层 SQLite 引擎版本。
+     *
+     * @returns 形如 `3.50.4` 的版本串
+     */
+    version(): string;
+    /**
+     * 断开连接并释放文件句柄。
+     *
+     * @remarks
+     * 关闭前回滚尚未提交的事务并做一次 TRUNCATE checkpoint（AC#7）：前者避免把半截状态留给下次启动，
+     * 后者把 WAL 内容并回主库文件，使调用方随后可以直接重命名/备份这个 `.sqlite3`，
+     * 而不必额外搬运 `-wal` / `-shm` 旁文件。
+     *
+     * 还攒在批次里的变更事件在这里**同步**发掉，与 `Oo1ClientBase.disconnect` 一致：
+     * 定时器随连接一起消失，不发就等于把最后一批写入的通知悄悄吞掉。
+     *
+     * 重复调用是安全的。
+     */
+    close(): void;
+}
+//# sourceMappingURL=node-sqlite-engine.d.ts.map

package/dist/node-sqlite-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-sqlite-engine.d.ts","sourceRoot":"","sources":["../src/node-sqlite-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EASL,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EAEzB,KAAK,YAAY,EAClB,MAAM,gCAAgC,CAAC;AAKxC,yCAAyC;AACzC,MAAM,WAAW,uBAAuB;IACtC,wCAAwC;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2BAA2B;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;IACtD,iEAAiE;IACjE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAyJD;;;;;;GAMG;AACH,qBAAa,gBAAgB;;IAe3B,OAAO;IASP;;;;;;;;;;OAUG;IACH,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,uBAAuB,GAAG,gBAAgB;IA2B/D;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,GAAE,SAAS,oBAAoB,EAAO,GAAG,YAAY;IAkBlF;;;;OAIG;IACH,OAAO,IAAI,MAAM;IAMjB;;;;;;;;;;;;OAYG;IACH,KAAK,IAAI,IAAI;CAuRd"}

package/dist/pglite/RxDBAdapterElectronPGlite.d.ts

@@ -0,0 +1,44 @@
+import { RxDB } from '@aiao/rxdb';
+import { RxDBAdapterPGlite, IPGliteClient } from '@aiao/rxdb-adapter-pglite';
+import { ADAPTER_NAME, ElectronPGliteOptions } from './pglite-adapter.interface.js';
+/**
+ * 把 RxDB 接到 Electron 主进程持有的那个唯一 PGlite 实例上。
+ *
+ * @remarks
+ * 数据落在主进程的应用数据目录里，renderer 只通过一条窄传输层发 `pg.*` 请求，
+ * 因此它既拿不到 OPFS 句柄，也拿不到物理路径（AC#5）。
+ *
+ * 适配器本身没有自己的查询实现：SQL 生成、迁移、变更管线、加密全部复用
+ * {@link RxDBAdapterPGlite}，只把 {@link RxDBAdapterPGlite.createClient} 这一个接缝
+ * 换成了 {@link DesktopPGliteClient}。这是刻意的——桌面与浏览器共用一份行为，
+ * 分叉出去的每一行都会变成「只在 Electron 下复现」的 bug。
+ *
+ * @example
+ * ```ts
+ * rxdb.registerAdapter(new RxDBAdapterElectronPGlite(rxdb));
+ * ```
+ */
+export declare class RxDBAdapterElectronPGlite extends RxDBAdapterPGlite {
+    #private;
+    name: string;
+    /** 解析出的逻辑数据目录名，与 host 侧的物理目录一一对应。 */
+    get dataDirectoryName(): string;
+    /**
+     * @param rxdb - 绑定的 RxDB 实例
+     * @param options - 传输层、逻辑数据目录名与两个超时窗口
+     * @throws {@link RxDBAdapterDesktopError} 逻辑数据目录名越出应用作用域时抛 `invalid_database_name`
+     */
+    constructor(rxdb: RxDB, options?: ElectronPGliteOptions);
+    /**
+     * 建出转发到主进程的客户端。
+     *
+     * @returns 尚未 `init()` 的桌面客户端；基类随后用 `rxdb.config.dbName` 初始化它
+     */
+    protected createClient(): IPGliteClient;
+}
+declare module '@aiao/rxdb' {
+    interface RxDBAdapters {
+        [ADAPTER_NAME]: RxDBAdapterElectronPGlite;
+    }
+}
+//# sourceMappingURL=RxDBAdapterElectronPGlite.d.ts.map

package/dist/pglite/RxDBAdapterElectronPGlite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RxDBAdapterElectronPGlite.d.ts","sourceRoot":"","sources":["../../src/pglite/RxDBAdapterElectronPGlite.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAAE,KAAK,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAMlF,OAAO,EAAE,YAAY,EAAiC,KAAK,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAExH;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,yBAA0B,SAAQ,iBAAiB;;IAGrD,IAAI,EAAE,MAAM,CAAgB;IAErC,qCAAqC;IACrC,IAAI,iBAAiB,IAAI,MAAM,CAE9B;IAED;;;;OAIG;gBACS,IAAI,EAAE,IAAI,EAAE,OAAO,GAAE,qBAA0B;IAU3D;;;;OAIG;cACgB,YAAY,IAAI,aAAa;CAQjD;AAED,OAAO,QAAQ,YAAY,CAAC;IAC1B,UAAU,YAAY;QACpB,CAAC,YAAY,CAAC,EAAE,yBAAyB,CAAC;KAC3C;CACF"}

package/dist/pglite/desktop-pglite-client.d.ts

@@ -0,0 +1,118 @@
+import { IPGliteClient, PGliteClientEvents, PGliteClientOptions } from '@aiao/rxdb-adapter-pglite';
+import { DesktopHostTransport } from '@aiao/rxdb-adapter-sqlite-core/desktop-host';
+import { EventDispatcher } from '@aiao/utils';
+import { QueryOptions, Results, Transaction } from '@electric-sql/pglite';
+/** {@link DesktopPGliteClient} 的构造参数。 */
+export interface DesktopPGliteClientOptions {
+    /** preload 或 worker 桥接提供的传输层。 */
+    readonly transport: DesktopHostTransport;
+    /** 应用作用域内的逻辑数据目录名；host 在自己的应用数据目录里解析它。 */
+    readonly dataDirectoryName: string;
+    /** `pg.begin` 的等待上限（毫秒）；省略时由 host 用协议默认值。 */
+    readonly beginTimeout?: number;
+    /** NOTIFY 批量窗口（毫秒）；省略时用 {@link DEFAULT_NOTIFY_BATCH_TIMEOUT_MS}。 */
+    readonly batchTimeout?: number;
+}
+/**
+ * 通过桌面 host 访问主进程 PGlite 实例的客户端。
+ *
+ * @remarks
+ * 两条串行化链各管一件事：
+ * - {@link DesktopPGliteClient.#tail} 是**会话内 FIFO**，保证发出顺序即执行顺序；
+ * - {@link DesktopPGliteClient.#lock} 是**本地互斥**，让事务独占整段时间。
+ *
+ * 后者不是可有可无的谨慎：主进程只有一条 PGlite 连接，一条事务开着时它被挂起的
+ * callback 攥着。没有本地互斥的话，第二条事务的 `pg.begin`（或一条自动提交语句）会排在
+ * 会话队列里等那条连接，而连接又要等第一条事务把剩下的语句发完——双方互相等，
+ * 表现为几秒后一句 `transaction_unavailable`，看上去像 host 有 bug。浏览器路径上
+ * PGlite 自己的 mutex 做的正是同一件事，这里只是把它挪到了进程边界的这一侧。
+ *
+ * @public
+ */
+export declare class DesktopPGliteClient extends EventDispatcher<PGliteClientEvents> implements IPGliteClient {
+    #private;
+    /** 本客户端在 host 上的会话 ID，用于把推送过来的 NOTIFY 对号入座。 */
+    get sessionId(): string;
+    /** host 解析出的逻辑位置，仅供诊断（AC#5）。 */
+    get resolvedLocation(): string;
+    /** 尚未分发的 NOTIFY 行事件数量。 */
+    get pendingNotificationCount(): number;
+    constructor(options: DesktopPGliteClientOptions);
+    /**
+     * 握手、打开会话并订阅变更推送。
+     *
+     * @remarks
+     * 握手排在 `pg.open` 之前是 AC#11 的全部内容：`pg.open` 会 `mkdir` 出数据目录并在里面
+     * 跑 initdb，等 renderer 从 open 应答里读出版本不匹配时，磁盘上已经多了一整棵目录树，
+     * 而调用方拿不到 client，也就没有把手去收拾它。
+     *
+     * @param dbName - RxDB 逻辑库名；只用于变更事件的 `dbName` 字段，不参与落盘位置解析
+     * @param options - PGlite 选项；**不得**含 `store` 或 `dataDir`
+     * @throws {@link RxDBAdapterDesktopError} 指定了落盘位置、协议版本不匹配或 host 打不开数据目录时
+     */
+    init(dbName: string, options: PGliteClientOptions): Promise<void>;
+    /**
+     * 执行一条带参数的语句（扩展查询协议）。
+     *
+     * @param query - SQL
+     * @param params - 位置参数
+     * @param options - **必须省略**，见 {@link assertNoQueryOptions}
+     * @returns 与浏览器路径同形状的结果
+     * @throws {@link RxDBAdapterDesktopError} 会话已关闭、传了 `options`，或 host 报告执行失败时
+     */
+    query<T>(query: string, params?: unknown[], options?: QueryOptions): Promise<Results<T>>;
+    /**
+     * 以标签模板执行一条语句，参数自动参数化。
+     *
+     * @param sqlStrings - 模板字面量片段
+     * @param params - 插值；`identifier` / `raw` / 嵌套 `sql` 辅助器按原语义处理
+     * @returns 与浏览器路径同形状的结果
+     * @throws {@link RxDBAdapterDesktopError} 会话已关闭，或 host 报告执行失败时
+     */
+    sql<T>(sqlStrings: TemplateStringsArray, ...params: unknown[]): Promise<Results<T>>;
+    /**
+     * 执行一段多语句脚本（简单查询协议）。
+     *
+     * @param query - 一条或多条以 `;` 分隔的语句
+     * @param options - **必须省略**，见 {@link assertNoQueryOptions}
+     * @returns 每条语句一个结果
+     * @throws {@link RxDBAdapterDesktopError} 会话已关闭、传了 `options`，或 host 报告执行失败时
+     */
+    exec(query: string, options?: QueryOptions): Promise<Results[]>;
+    /**
+     * 在主进程那条唯一连接上开一条真事务。
+     *
+     * @remarks
+     * 回调拿到的 `tx` 是个代理：它的每条语句都带着 host 签发的事务 ID 过去，因此确实落在
+     * 同一条 PostgreSQL 事务里，而不是被包装成「看起来像事务」的独立请求（AC#2）。
+     * 回调正常返回即 `pg.commit`，抛出即 `pg.rollback`——与 PGlite 自己的语义一致。
+     *
+     * @param callback - 事务体
+     * @returns 回调的返回值
+     * @throws 回调抛出的原始异常（事务已回滚），或 {@link RxDBAdapterDesktopError}
+     */
+    transaction<T>(callback: (tx: Transaction) => Promise<T>): Promise<T>;
+    /**
+     * 报告 host 侧 PostgreSQL 的版本串。
+     *
+     * @returns 形如 `PostgreSQL 17.x ...` 的版本串
+     */
+    version(): Promise<string>;
+    /**
+     * 断开会话。
+     *
+     * @remarks
+     * 等在途请求与开着的事务跑完再关，因此调用方返回时 host 上确实已经没有本会话的
+     * 任何残留。并发调用共享同一个关闭流程。
+     */
+    disconnect(): Promise<void>;
+    /**
+     * 不等在途请求，直接让 host 释放本会话。
+     *
+     * @remarks
+     * host 收到 `pg.close` 会把本会话仍开着的事务全部回滚，因此「不等」丢掉的只是那些
+     * 未提交的写——这正是 `forceClose` 与 {@link DesktopPGliteClient.disconnect} 的区别。
+     */
+    forceClose(): Promise<void>;
+}
+//# sourceMappingURL=desktop-pglite-client.d.ts.map

package/dist/pglite/desktop-pglite-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"desktop-pglite-client.d.ts","sourceRoot":"","sources":["../../src/pglite/desktop-pglite-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAML,KAAK,oBAAoB,EAI1B,MAAM,6CAA6C,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAM/E,yCAAyC;AACzC,MAAM,WAAW,0BAA0B;IACzC,iCAAiC;IACjC,QAAQ,CAAC,SAAS,EAAE,oBAAoB,CAAC;IACzC,0CAA0C;IAC1C,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,6CAA6C;IAC7C,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,oEAAoE;IACpE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAuED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,mBAAoB,SAAQ,eAAe,CAAC,kBAAkB,CAAE,YAAW,aAAa;;IAcnG,+CAA+C;IAC/C,IAAI,SAAS,IAAI,MAAM,CAKtB;IAED,gCAAgC;IAChC,IAAI,gBAAgB,IAAI,MAAM,CAK7B;IAED,0BAA0B;IAC1B,IAAI,wBAAwB,IAAI,MAAM,CAErC;gBAEW,OAAO,EAAE,0BAA0B;IAW/C;;;;;;;;;;;OAWG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IA8BvE;;;;;;;;OAQG;IACG,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAM9F;;;;;;;OAOG;IACG,GAAG,CAAC,CAAC,EAAE,UAAU,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAMzF;;;;;;;OAOG;IACG,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAMrE;;;;;;;;;;;OAWG;IACG,WAAW,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAK3E;;;;OAIG;IACG,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;IAShC;;;;;;OAMG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAKjC;;;;;;OAMG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;CA0MlC"}

package/dist/pglite/pglite-adapter.interface.d.ts

@@ -0,0 +1,56 @@
+import { DesktopHostTransport } from '@aiao/rxdb-adapter-sqlite-core/desktop-host';
+/**
+ * 适配器在 `RxDBAdapters` 注册表中的名字。
+ *
+ * @remarks
+ * 与 `sqlite-electron` 并列，同一个 Electron 运行时上两个适配器可以同时注册
+ * （US-207 已为此把 SQLite 侧的名字从 `electron` 改成了 `sqlite-electron`）。
+ *
+ * 这里**刻意不写** `satisfies DesktopHostAdapterName`：那份登记表是「走 SQLite host
+ * 协议的适配器」的清单，PGlite 走的是另一族协议（`pg.*`）。硬套上去会让共享层的
+ * 存储联合把 `pglite-electron` 也当成能接受 `DesktopSqliteFileStorage` 的适配器。
+ */
+export declare const ADAPTER_NAME: "pglite-electron";
+/**
+ * 逻辑数据目录名的默认后缀。
+ *
+ * @remarks
+ * 与 SQLite 侧的 `DEFAULT_DATABASE_SUFFIX` 同构，但后缀不同：PGlite 落盘的是一棵
+ * initdb 生成的**目录树**而不是单个文件，用 `.db` 之类的文件后缀命名只会误导运维。
+ */
+export declare const DEFAULT_DATA_DIRECTORY_SUFFIX = "-pgdata";
+/** {@link RxDBAdapterElectronPGlite} 的构造选项。 */
+export interface ElectronPGliteOptions {
+    /**
+     * 传输层；省略时从 `globalThis` 上读取 preload 注入的那一份。
+     *
+     * @remarks
+     * 显式传入主要供测试与非 Electron 宿主使用，见
+     * {@link @aiao/rxdb-adapter-sqlite-core/desktop-host#resolveDesktopHostTransport}。
+     */
+    readonly transport?: DesktopHostTransport;
+    /**
+     * 应用作用域内的逻辑数据目录名；省略时为 `<dbName>-pgdata`。
+     *
+     * @remarks
+     * 只能是名字，不能是路径：物理根目录由主进程决定，renderer 既拿不到也不需要
+     * （AC#5）。含路径分隔符时在构造期就抛 `invalid_database_name`。
+     */
+    readonly dataDirectoryName?: string;
+    /**
+     * `pg.begin` 等待主进程那条唯一连接的上限（毫秒）。
+     *
+     * @remarks
+     * 省略时用协议默认值 `DESKTOP_PGLITE_DEFAULT_BEGIN_TIMEOUT_MS`。它约束的是**跨窗口**
+     * 的竞争：同一个客户端内部的事务由本地互斥串行化，根本不会互相超时。
+     */
+    readonly beginTimeout?: number;
+    /**
+     * NOTIFY 批量窗口（毫秒）；省略时用 `DEFAULT_NOTIFY_BATCH_TIMEOUT_MS`。
+     *
+     * @remarks
+     * 与浏览器路径同义、同实现——批量发生在渲染进程，主进程只转发裸 NOTIFY。
+     */
+    readonly batchTimeout?: number;
+}
+//# sourceMappingURL=pglite-adapter.interface.d.ts.map

package/dist/pglite/pglite-adapter.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pglite-adapter.interface.d.ts","sourceRoot":"","sources":["../../src/pglite/pglite-adapter.interface.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6CAA6C,CAAC;AAExF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,EAAG,iBAA0B,CAAC;AAEvD;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,YAAY,CAAC;AAEvD,+CAA+C;AAC/C,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,oBAAoB,CAAC;IAC1C;;;;;;OAMG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC"}

package/dist/pglite-host/electron-pglite-host.d.ts

@@ -0,0 +1,114 @@
+import { DesktopPgliteNotifyMessage, DesktopPgliteResponse } from '@aiao/rxdb-adapter-sqlite-core/desktop-host';
+/**
+ * host 代 renderer 订阅的 NOTIFY 频道。
+ *
+ * @remarks
+ * 与 `@aiao/rxdb-adapter-pglite` 里 `PGliteClient` 监听的三张系统表一一对应。
+ * PostgreSQL 只把 `LISTEN` 过的频道推给连接，因此这份清单漏一项就等于对应的响应式
+ * 查询在桌面下永远不刷新——而浏览器下一切正常，排查时几乎不会怀疑到订阅清单上。
+ */
+export declare const DESKTOP_PGLITE_WATCH_CHANNELS: readonly string[];
+/** 一条语句的结果；`ElectronPgliteRuntime` 与 PGlite 的 `Results` 在此结构相容。 */
+export interface ElectronPgliteRuntimeResult {
+    readonly rows: Record<string, unknown>[];
+    readonly fields: {
+        name: string;
+        dataTypeID: number;
+    }[];
+    readonly affectedRows?: number;
+}
+/** 事务句柄；对应 PGlite 的 `Transaction`，只声明 host 真正用到的两个操作。 */
+export interface ElectronPgliteTransaction {
+    query(sql: string, params?: unknown[]): Promise<ElectronPgliteRuntimeResult>;
+    exec(sql: string): Promise<ElectronPgliteRuntimeResult[]>;
+}
+/**
+ * host 需要的 PGlite 能力子集。
+ *
+ * @remarks
+ * 刻意不写成 `PGliteInterface`：宿主应用极可能传进来的不是裸 `PGlite`，而是跑在 worker
+ * 里的 `PGliteWorker`——PGlite 的 WASM 在主进程 JS 线程上是**同步**执行的，一条重查询会
+ * 把整个窗口的 IPC 一起卡住（故事「冻结带来的三条实现约束」第 3 条）。声明成结构类型后，
+ * 两者都能直接传入，而这份清单也顺便说清了 host 只需要这五个操作。
+ */
+export interface ElectronPgliteRuntime {
+    query(sql: string, params?: unknown[]): Promise<ElectronPgliteRuntimeResult>;
+    exec(sql: string): Promise<ElectronPgliteRuntimeResult[]>;
+    transaction<T>(callback: (tx: ElectronPgliteTransaction) => Promise<T>): Promise<T>;
+    listen(channel: string, callback: (payload: string) => void): Promise<unknown>;
+    close(): Promise<void>;
+}
+/** {@link createElectronPgliteHost} 的入参。 */
+export interface ElectronPgliteHostOptions {
+    /**
+     * 按逻辑数据目录名创建一个 PGlite 运行时。
+     *
+     * @remarks
+     * **必填，没有默认实现**：默认值只能是「在某处建一个 PGlite」，而那个「某处」只有宿主
+     * 应用知道（Electron 下通常在 `app.getPath('userData')` 之下）。给一个兜底目录意味着
+     * 数据会静默落在谁也没打算用的位置，而症状是「重启后数据没了」。
+     *
+     * 传进来的名字已过白名单校验，不含任何路径分隔符，因此 `join(root, name)` 不会越出 `root`。
+     * 同一个名字在 host 生命周期内只会被调用一次（AC#7）。
+     */
+    readonly createRuntime: (dataDirectoryName: string) => Promise<ElectronPgliteRuntime>;
+    /** 把裸 NOTIFY 送达对应会话的 renderer，例如 `webContents.send`。 */
+    readonly postNotify: (message: DesktopPgliteNotifyMessage) => void;
+    /**
+     * NOTIFY 送达失败时的上报口。
+     *
+     * @remarks
+     * 与 SQLite host 同理：窗口在通知投递途中被销毁是常规竞态，此时写入早已落库，
+     * 把送达失败当成写失败回给调用方只会诱发一次重复写入。不传则丢弃。
+     */
+    readonly onDeliveryError?: (error: unknown) => void;
+}
+/** 桌面 PGlite host 实例。 */
+export interface ElectronPgliteHost {
+    /**
+     * 处理一条来自 renderer 的请求。
+     *
+     * @remarks
+     * **永不 reject**：失败以 `kind: 'error'` 的应答返回，理由与 SQLite host 一致
+     * （`ipcRenderer.invoke` 在 reject 时会把错误压平成字符串，错误码随之丢失）。
+     *
+     * @param request - 未经校验的请求负载
+     * @param ownerId - 发起方的 `webContents.id`；会话与事务都按它归属
+     * @returns 协议应答
+     */
+    handle(request: unknown, ownerId: number): Promise<DesktopPgliteResponse>;
+    /** 当前打开的会话数。 */
+    readonly openSessionCount: number;
+    /** 当前活着的 PGlite 实例数；同一个数据目录上的多个会话只算一个。 */
+    readonly openInstanceCount: number;
+    /** 当前挂起的事务数；正常静止时应为 0。 */
+    readonly openTransactionCount: number;
+    /**
+     * 回收某个窗口名下的全部会话与事务。
+     *
+     * @remarks
+     * 这是本方案的**前提而非收尾**：挂起的 callback 独占 PGlite 的连接锁，渲染进程崩在
+     * 事务中间而没人回收的话，之后任何查询都会永远排队——表征是「数据库不响应」，
+     * 与那次崩溃毫无关联线索。调用方必须把它挂到 `render-process-gone` 与 `destroyed`
+     * 两个事件上（AC#3）。
+     *
+     * @param ownerId - 已崩溃或已销毁的 `webContents.id`
+     * @returns 本次回滚掉的事务条数
+     */
+    releaseOwner(ownerId: number): Promise<number>;
+    /** 关闭全部会话与实例，通常在应用退出前调用。 */
+    closeAll(): Promise<void>;
+}
+/**
+ * 创建一个桌面 PGlite host。
+ *
+ * @remarks
+ * 与 SQLite host 相反，同一个数据目录上的多个会话**共享一个** PGlite 实例（AC#7）：
+ * PGlite 是嵌入式单写者，同一份数据目录被两个实例同时打开会直接损坏它。跨窗口的并发
+ * 因此由这一条连接的排队来串行化，而不是交给文件锁。
+ *
+ * @param options - host 配置
+ * @returns host 实例
+ */
+export declare function createElectronPgliteHost(options: ElectronPgliteHostOptions): ElectronPgliteHost;
+//# sourceMappingURL=electron-pglite-host.d.ts.map

package/dist/pglite-host/electron-pglite-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"electron-pglite-host.d.ts","sourceRoot":"","sources":["../../src/pglite-host/electron-pglite-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAIL,KAAK,0BAA0B,EAG/B,KAAK,qBAAqB,EAC3B,MAAM,6CAA6C,CAAC;AAarD;;;;;;;GAOG;AACH,eAAO,MAAM,6BAA6B,EAAE,SAAS,MAAM,EAIzD,CAAC;AAEH,mEAAmE;AACnE,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACxD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,yDAAyD;AACzD,MAAM,WAAW,yBAAyB;IACxC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAAC;IAC7E,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,2BAA2B,EAAE,CAAC,CAAC;CAC3D;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAAC;IAC7E,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,2BAA2B,EAAE,CAAC,CAAC;IAC1D,WAAW,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,EAAE,yBAAyB,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACpF,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,4CAA4C;AAC5C,MAAM,WAAW,yBAAyB;IACxC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,aAAa,EAAE,CAAC,iBAAiB,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACtF,wDAAwD;IACxD,QAAQ,CAAC,UAAU,EAAE,CAAC,OAAO,EAAE,0BAA0B,KAAK,IAAI,CAAC;IACnE;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACrD;AAED,yBAAyB;AACzB,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;;;OAUG;IACH,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC1E,gBAAgB;IAChB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,0CAA0C;IAC1C,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,0BAA0B;IAC1B,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC;;;;;;;;;;;OAWG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/C,4BAA4B;IAC5B,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAqFD;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,yBAAyB,GAAG,kBAAkB,CAoV/F"}

package/dist/pglite-host.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `@aiao/rxdb-adapter-electron` 的 **PGlite 特权侧**入口。
+ *
+ * @remarks
+ * 与 `@aiao/rxdb-adapter-electron/host` 分开而不是并进去，理由是依赖：那个入口只要
+ * `node:sqlite`（Node 内建，装了就有），本入口却要 `@electric-sql/pglite` 这个可选 peer。
+ * 合并的话，任何一个只用 SQLite 的宿主应用都会在加载 host 时撞上「找不到
+ * `@electric-sql/pglite`」——而它压根没打算用 PGlite。
+ *
+ * 本入口只能在有 Node 运行时的地方加载（Electron 主进程，或它自己拥有的 worker）。
+ * renderer 侧请用 `@aiao/rxdb-adapter-electron/pglite`。
+ *
+ * @module @aiao/rxdb-adapter-electron/pglite-host
+ */
+export { DESKTOP_PGLITE_WATCH_CHANNELS, createElectronPgliteHost, type ElectronPgliteHost, type ElectronPgliteHostOptions, type ElectronPgliteRuntime, type ElectronPgliteRuntimeResult, type ElectronPgliteTransaction } from './pglite-host/electron-pglite-host.js';
+export { DESKTOP_PGLITE_DEFAULT_BEGIN_TIMEOUT_MS, DESKTOP_PGLITE_MAX_BEGIN_TIMEOUT_MS, DESKTOP_PGLITE_PROTOCOL_VERSION, RxDBAdapterDesktopError, assertValidDesktopDatabaseName, isDesktopPgliteRequestKind, parseDesktopPgliteRequest, type DesktopPgliteNotifyMessage, type DesktopPgliteQueryResult, type DesktopPgliteRequest, type DesktopPgliteResponse, type RxDBAdapterDesktopErrorCode } from '@aiao/rxdb-adapter-sqlite-core/desktop-host';
+//# sourceMappingURL=pglite-host.d.ts.map

package/dist/pglite-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pglite-host.d.ts","sourceRoot":"","sources":["../src/pglite-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,6BAA6B,EAC7B,wBAAwB,EACxB,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC9B,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,EAChC,KAAK,yBAAyB,EAC/B,MAAM,uCAAuC,CAAC;AAI/C,OAAO,EACL,uCAAuC,EACvC,mCAAmC,EACnC,+BAA+B,EAC/B,uBAAuB,EAGvB,8BAA8B,EAC9B,0BAA0B,EAC1B,yBAAyB,EACzB,KAAK,0BAA0B,EAC/B,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,EACjC,MAAM,6CAA6C,CAAC"}