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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Aiao Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,294 @@
-# Temporary Holding Version
+# @aiao/rxdb-adapter-electron
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+RxDB 适配器，把数据落到 **Electron 应用私有目录里的真实文件**。本包提供两个并列的适配器，可同时注册：
+
+| 适配器名          | 落盘形态                   | 入口                                            |
+| ----------------- | -------------------------- | ----------------------------------------------- |
+| `sqlite-electron` | 单个 `.sqlite3` 文件       | `.`（renderer）+ `/host`（特权侧）              |
+| `pglite-electron` | 一棵 PGlite data directory | `/pglite`（renderer）+ `/pglite-host`（特权侧） |
+
+数据由特权侧（Electron 主进程或它拥有的 worker）直接读写——SQLite 走 `node:sqlite`，PGlite 走 `@electric-sql/pglite` 的 Node filesystem backend；渲染进程只通过一条窄传输层发协议请求，因此它既拿不到文件系统句柄，也拿不到物理路径。
+
+Tauri 请改用 [`@aiao/rxdb-adapter-tauri`](https://www.npmjs.com/package/@aiao/rxdb-adapter-tauri)：协议与 renderer 客户端两包共用同一份实现（在 `@aiao/rxdb-adapter-sqlite-core/desktop-host`），差别只在特权侧是 `node:sqlite` 还是 Rust。
+
+## 功能特性
+
+- **真文件持久化**：数据在应用数据目录里（SQLite 是 `.sqlite3` 文件，PGlite 是一棵 data directory），重启后仍在，不依赖浏览器存储配额
+- **渲染进程零文件系统权限**：`contextIsolation: true` + `sandbox: true` 下照常工作
+- **多窗口安全**：两族各有各的做法，且**行为不同**——见下方[多窗口与事务](#多窗口与事务)
+- **不回退**：存储配置不受支持时直接抛错，绝不静默切到 memory/OPFS/IndexedDB
+- **复用引擎核心**：查询、事务、分支切换来自 `@aiao/rxdb-adapter-sqlite-core` / `@aiao/rxdb-adapter-pglite`，与各自的浏览器档位同语义、同一批测试套件
+
+## 何时使用
+
+- Electron 应用需要「用户看得见、备份得了、卸载才会没」的本地数据
+- 数据量超出浏览器存储配额的舒适区，或不接受 OPFS 被浏览器回收的风险
+- 需要外部工具直接打开同一份数据（SQLite：`sqlite3` CLI、DB Browser）
+
+两族之间怎么选：默认选 `sqlite-electron`——单文件、外部工具好接、依赖只有 Node 内建。需要 PostgreSQL 的类型与 SQL 方言（JSONB、关系约束），或需要变更事件跨窗口（`LISTEN`/`NOTIFY`，见下方[多窗口与事务](#多窗口与事务)）时才选 `pglite-electron`，代价是几十兆 WASM 和一条 worker 线程。
+
+> **全文搜索两族都还用不了**：`@aiao/rxdb-plugin-search` 的放行名单里只有浏览器内的引擎（`sqlite-wasm` / `sqlite` / `sqliteai` / `pglite`），两个桌面适配器名都不在表内，`createRxDatabase` 阶段会抛 `SearchUnsupportedAdapterError`——不降级、不挂 `.search`。
+
+浏览器内运行请改用 [`@aiao/rxdb-adapter-wa-sqlite`](https://www.npmjs.com/package/@aiao/rxdb-adapter-wa-sqlite) 或 [`@aiao/rxdb-adapter-sqlite-wasm`](https://www.npmjs.com/package/@aiao/rxdb-adapter-sqlite-wasm)。
+
+## 能力矩阵
+
+| 存储                  | 状态                                                                                          |
+| --------------------- | --------------------------------------------------------------------------------------------- |
+| SQLite 单文件         | ✅ host 在包内（`/host`），适配器名 `sqlite-electron`                                         |
+| PGlite data directory | ✅ host 在包内（`/pglite-host`），适配器名 `pglite-electron`；需要可选 peer（见下方「安装」） |
+
+两族走的是**两套协议**（SQLite 侧 `sqlite.*`，PGlite 侧 `pg.*`），不是同一个协议的两种后端：PGlite 的 callback transaction 跨不过 IPC，只能用显式的事务 ID 协议（`begin` / `query` / `commit` / `rollback`，同一事务 ID 绑定同一条物理连接）。所以 `pglite-electron` **刻意不在** `DesktopHostAdapterName` 登记表里——那份表是「走 SQLite host 协议」的清单，硬套上去会让共享层误以为它能接受 `DesktopSqliteFileStorage`。
+
+不在矩阵内的组合会被 `assertDesktopSqliteStorage` 以 `unsupported_runtime_engine` 拒绝——不静默退化。
+
+host 侧需要一个 Node 运行时：SQLite 侧要内置 `node:sqlite`，PGlite 侧要能加载 `@electric-sql/pglite`。本包在 Node 26 与 Electron 43 上验证，更早的版本未验证。
+
+## 安装
+
+```bash
+npm install @aiao/rxdb-adapter-electron
+# 或
+pnpm add @aiao/rxdb-adapter-electron
+```
+
+只用 SQLite 的话装到这里就够了。**要用 PGlite 才需要**再装两个可选 peer：
+
+```bash
+pnpm add @aiao/rxdb-adapter-pglite @electric-sql/pglite
+```
+
+两者都声明为 `optional: true` 的 peer，正是为了让只用 SQLite 的应用不必装 PGlite——这也是下面四个入口必须分开的原因。
+
+## 四个入口
+
+包**刻意**分成四个入口，不要混用。分法是两条正交的线：**renderer / 特权侧**（谁能碰文件系统）× **SQLite / PGlite**（引入哪个可选 peer）。
+
+| 入口                                      | 加载位置                          | 引入的重依赖                                   |
+| ----------------------------------------- | --------------------------------- | ---------------------------------------------- |
+| `@aiao/rxdb-adapter-electron`             | renderer（浏览器上下文）          | 无，可安全打进 bundle                          |
+| `@aiao/rxdb-adapter-electron/host`        | Electron 主进程 / 它拥有的 worker | `node:sqlite`                                  |
+| `@aiao/rxdb-adapter-electron/pglite`      | renderer（浏览器上下文）          | 仅 `@aiao/rxdb-adapter-pglite` + 类型，见下    |
+| `@aiao/rxdb-adapter-electron/pglite-host` | Electron 主进程 / 它拥有的 worker | `@electric-sql/pglite`（完整 PostgreSQL WASM） |
+
+把任一 host 入口打进 renderer bundle 等于把文件系统能力还给渲染进程，整个隔离随之作废。
+
+> `/pglite` 这个 renderer 入口**不引用 PostgreSQL 运行时**：WASM 实例活在特权侧，renderer 这边只有一层协议代理，从 `@electric-sql/pglite` 取的只有类型和 `/template` 那个约 2 KB 的模板编译子路径。所以用 PGlite 不会让 renderer bundle 多出几十兆。
+
+## 使用
+
+接线分三处。
+
+### 1. 主进程：起 host
+
+```typescript
+import { createElectronSqliteHost } from '@aiao/rxdb-adapter-electron/host';
+import { app, ipcMain, type WebContents } from 'electron';
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+const root = join(app.getPath('userData'), 'rxdb-data');
+
+// sessionId → 该会话归属的窗口。open 应答里带 sessionId，变更事件按它回送。
+const targets = new Map<string, WebContents>();
+
+const host = createElectronSqliteHost({
+  // 只有宿主应用知道自己的数据目录。传进来的名字已过白名单校验，不含任何路径分隔符。
+  resolveDatabasePath: databaseName => {
+    mkdirSync(root, { recursive: true });
+    return join(root, databaseName);
+  },
+  postChange: message => {
+    const target = targets.get(message.sessionId);
+    // 窗口已经没了：写入早已落库，事件无处可送。这是常规竞态而不是失败。
+    if (!target || target.isDestroyed()) return;
+    target.send('desktop-sqlite:change', message);
+  },
+  onDeliveryError: error => console.warn('[desktop-sqlite] 变更事件送达失败', error)
+});
+
+// host.handle 永不 reject：失败以 `kind: 'error'` 的应答返回。
+// ipcRenderer.invoke 在 reject 时会把错误压平成字符串，自定义错误码随之丢失。
+ipcMain.handle('desktop-sqlite:request', async (event, payload: unknown) => {
+  const response = await host.handle(payload);
+  if (response.kind === 'open') targets.set(response.result.sessionId, event.sender);
+  return response;
+});
+
+app.on('before-quit', () => host.closeAll());
+```
+
+会话回收（窗口 `destroyed` 时关掉它名下未关闭的会话）比上面这段更啰嗦一些，完整实现见文末示例里的 `desktop-sqlite-bridge.ts`。
+
+### 2. preload：暴露传输层
+
+传输层只有两个方法，renderer 因此拿不到原始 `ipcRenderer`，无法向任意频道发消息。
+
+```typescript
+import { contextBridge, ipcRenderer, type IpcRendererEvent } from 'electron';
+
+// 必须与适配器的 DESKTOP_HOST_TRANSPORT_KEY 逐字相同。
+contextBridge.exposeInMainWorld('__aiaoRxdbDesktopHost__', {
+  request: (payload: unknown) => ipcRenderer.invoke('desktop-sqlite:request', payload),
+  subscribe: (listener: (message: unknown) => void) => {
+    // 只转消息本体：IpcRendererEvent 带着 sender，交给 renderer 等于把通道能力一并送出。
+    const forward = (_event: IpcRendererEvent, message: unknown): void => listener(message);
+    ipcRenderer.on('desktop-sqlite:change', forward);
+    return () => ipcRenderer.removeListener('desktop-sqlite:change', forward);
+  }
+});
+```
+
+### 3. renderer：像用别的适配器一样用
+
+```typescript
+import { RxDB, SyncType } from '@aiao/rxdb';
+import { ELECTRON_ADAPTER_NAME, RxDBAdapterElectron } from '@aiao/rxdb-adapter-electron';
+
+const rxdb = new RxDB({
+  dbName: 'demo',
+  entities: [],
+  sync: { type: SyncType.None, local: { adapter: ELECTRON_ADAPTER_NAME } }
+});
+
+// 不传 transport：适配器自己去全局键上找 preload 暴露的桥接。
+rxdb.adapter(ELECTRON_ADAPTER_NAME, async database => new RxDBAdapterElectron(database));
+rxdb.init();
+await rxdb.connect(ELECTRON_ADAPTER_NAME);
+
+// 组件/窗口销毁时把连接交还给 host，否则会话要等到窗口 'destroyed' 才回收。
+await rxdb.disconnectAll();
+```
+
+### 换成 PGlite
+
+renderer 侧只换两个名字，其余逐字相同——传输层、preload、错误契约三者两族共用：
+
+```typescript
+import { ELECTRON_PGLITE_ADAPTER_NAME, RxDBAdapterElectronPGlite } from '@aiao/rxdb-adapter-electron/pglite';
+
+rxdb.adapter(
+  ELECTRON_PGLITE_ADAPTER_NAME,
+  async database => new RxDBAdapterElectronPGlite(database, { dataDirectoryName: 'demo-pgdata' })
+);
+```
+
+特权侧则换成 `createElectronPgliteHost`（来自 `/pglite-host`），并按上面「PGlite host 不要放在主线程」放进 worker。两个适配器可以在同一个 `RxDB` 实例上同时注册——名字不同，协议也不同。
+
+#### 共用一条 IPC 通道时的分派
+
+不必为 PGlite 新开通道：一条 `request` / `subscribe` 就够，主进程按请求的 `kind` 分派给三族 host（SQLite / 文件 / PGlite）。**顺序不能反**——
+
+```typescript
+// 1. 先做闭集守卫：未知 kind 在任何 host 被触碰之前就收口
+if (!isKnownDesktopHostRequestKind(request)) {
+  return Promise.resolve({ kind: 'error', code: 'protocol_violation', message: '...' });
+}
+// 2. 再分派；SQLite 只能垫底
+const kind = readDesktopHostRequestKind(request);
+if (isDesktopHostFileRequestKind(kind)) return file.handle(target, request);
+if (isDesktopPgliteRequestKind(kind)) return pglite.handle(target, request);
+return sqlite.handle(target, request);
+```
+
+SQLite 那支是**兜底分支**（「不是 handshake/open/version/close 的」一律当 `execute`），所以漏判一族的后果不是报错，而是一条 PGlite 请求被顺着 SQL 路径跑一遍。两层因此都要有：分派判据用协议包导出的 `isDesktopPgliteRequestKind`（`/pglite-host`）与 `isDesktopHostFileRequestKind`（`/host`），不要在接线处自己列 `kind` 名单——那份名单必然随协议版本漂移；闭集守卫则是应用侧自己的几行（协议未导出 SQLite 族谓词），负责把三族之外的 `kind` 挡在兜底分支之前。
+
+> 把 PGlite 接进来不会让只用 SQLite 的会话变重：示例里的 PGlite 通道工厂是**惰性调用**的，没有 `pg.*` 请求就不会启动那条 worker 线程、也不会加载 PostgreSQL WASM。
+
+完整实现见文末示例里的 `desktop-host-bridge.ts` 与 `desktop-host-request-guard.ts`。
+
+## 逻辑库名不是路径
+
+`databaseName` 是**应用作用域内的逻辑名**。renderer 无从得知、也不需要得知物理根目录。
+
+省略时按 `${rxdb.config.dbName}.sqlite3` 推导；PGlite 侧的对应项是 `dataDirectoryName`，省略时按 `${rxdb.config.dbName}-pgdata` 推导（落盘的是 initdb 生成的**目录树**而不是单个文件，用 `.db` 之类的文件后缀命名只会误导运维）。只有接管一个已存在的库、或多个 RxDB 实例共用同一个文件时才需要显式指定。
+
+允许集是白名单 `/^[A-Za-z0-9][A-Za-z0-9._@-]*$/`（≤ 128 字符）而非黑名单：字符集里没有 `/`、`\`、`:`，也不允许以 `.` 开头，于是 `..`、绝对路径、盘符、`~` 展开、URL scheme 全部落在集合外，不需要逐一枚举攻击形态。违反时抛 `invalid_database_name`。
+
+> 名字来自 renderer，即便有 `contextIsolation` 也**不可信**。host 侧会再校验一次；宿主应用的 `resolveDatabasePath` 里建议在 `mkdir` 之前再调一次 `assertValidDesktopDatabaseName` —— 非法入参不该在磁盘上留下任何痕迹。
+
+## ⚠️ 库目录不要叫 `databases`
+
+在 Electron 的 `userData` 下选子目录名时，**避开 `databases`**：那是 Chromium 自己的 WebSQL 目录，它的存储层启动时会把目录里没有登记过的文件全部删掉——你的库文件正是「没登记过的」。
+
+实测（打包产物，macOS，同一个 `--user-data-dir` 连开两次）：第一次启动写入的数据在第二次启动时被整体清空，全程**没有任何报错**，应用照常显示已连接、照常写入，只是上一次的数据没了。同一层级另建的 `rxdb-data/` 毫发无损。
+
+## 错误码
+
+程序分支请读 `error.code`，不要匹配消息文本（消息以 `[code] ` 前缀开头，仅便于日志检索）。原始原因通过 `cause` 原样透传。
+
+| code                         | 含义                                                                          |
+| ---------------------------- | ----------------------------------------------------------------------------- |
+| `unsupported_runtime_engine` | 存储 `engine` 不在能力矩阵内（例如把 PGlite data directory 递给 SQLite 协议） |
+| `invalid_database_name`      | 逻辑库名非法，或试图越出应用作用域                                            |
+| `host_unavailable`           | renderer 拿不到 host（未注入 transport / preload 未暴露）                     |
+| `session_closed`             | 会话已断开后继续使用                                                          |
+| `protocol_violation`         | 请求或响应不符合协议形状                                                      |
+| `open_failed`                | 打开数据库失败，`cause` 保留原始原因                                          |
+| `permission_denied`          | 路径无权限，或语句被 SQLite 授权器拒绝（`ATTACH` / `VACUUM INTO` 等）         |
+| `database_corrupted`         | 目标文件不是可用的 SQLite 数据库                                              |
+| `statement_failed`           | SQL 本身执行失败（语法、约束等）                                              |
+| `host_internal_error`        | host 自身出错，属于缺陷而非调用方问题                                         |
+| `database_busy`              | 另一个连接（通常是另一个窗口）正持有冲突的锁，重试即可，数据无损              |
+| `file_not_found`             | 目标文件或目录不存在；renderer 侧据此还原成 `NotFoundError`                   |
+| `invalid_file_path`          | 路径逃出存储根，或指向的类型与操作不符                                        |
+| `disk_full`                  | 磁盘空间或配额耗尽（ENOSPC / EDQUOT）                                         |
+| `write_aborted`              | 写入令牌已失效（会话关闭、已提交或已丢弃），目标保持写入前的内容              |
+| `transaction_not_found`      | 事务 ID 未知、已结束，或不属于本会话；该事务一条语句都没执行                  |
+| `transaction_unavailable`    | 等不到 PGlite 连接（另一个事务仍持有），或开启该事务的 `begin` 已超时         |
+
+`file_not_found` / `invalid_file_path` / `disk_full` / `write_aborted` 来自文件宿主（`createElectronFileHost`，供 `@aiao/rxdb-plugin-storage/desktop` 使用），SQLite 侧用不到。
+
+最后两个码只出现在 PGlite 路径上：PGlite 的事务靠显式事务 ID 串联多次 IPC，SQLite 侧没有这个概念。`transaction_unavailable` 的超时预算由 `DESKTOP_PGLITE_DEFAULT_BEGIN_TIMEOUT_MS` 给出，上限是 `DESKTOP_PGLITE_MAX_BEGIN_TIMEOUT_MS`。
+
+错误码是**契约的一部分**：新增只能追加，不得复用或改写既有含义。
+
+`RxDBAdapterDesktopError` 这个类跨不过结构化克隆，host 侧的错误以 `{ kind: 'error', code, message }` 回到 renderer，由适配器按契约重新抛成 `RxDBAdapterDesktopError`——调用方写的仍是普通 `try/catch`，感觉不到中间隔着一条 IPC。不在契约内的 `code` 一律按 `protocol_violation` 处理，不会被当成错误码原样上抛。
+
+## 多窗口与事务
+
+**两族在这一节上的行为不同**，这是选型时最容易踩的一处差异：
+
+| 维度       | `sqlite-electron`                          | `pglite-electron`                                       |
+| ---------- | ------------------------------------------ | ------------------------------------------------------- |
+| 连接模型   | 每个 `open` 一条独立连接                   | 同一数据目录**共用一个实例**，跨会话复用                |
+| 并发写     | SQLite 文件锁 + 退避重试 → `database_busy` | 事务在唯一连接上排队 → 超时报 `transaction_unavailable` |
+| 变更跨窗口 | ❌ 不跨（见下）                            | ✅ 跨，`NOTIFY` 扇出到该实例的全部会话                  |
+
+### SQLite：`BEGIN IMMEDIATE` 与撞锁重试
+
+事务用 `BEGIN IMMEDIATE` 而非裸 `BEGIN`：后者延迟取锁，写锁要等到事务里第一条写语句才拿，撞锁于是发生在**事务中途**——那时已经读过一份快照，SQLite 要求整个事务回滚重来。`IMMEDIATE` 把取锁挪到起点，撞锁时事务还没开，重试就是无副作用地再发一次。
+
+撞锁后按指数退避重试，默认总预算 5 秒（盖住「另一个窗口正在跑一次系统 schema 迁移」这段最长持锁时间），超时报 `database_busy`。可用 host 的 `busyRetryBudgetMs` 调整。
+
+#### 变更事件不跨窗口
+
+每个 `open` 得到一条**独立**的 `DatabaseSync` 连接——共享连接会让多个窗口的 `BEGIN` 块互相穿插，事务隔离直接失效。代价是变更通知只在写入所在的那条连接上开火：通知靠 TEMP 触发器实现，而 TEMP 对象是连接私有的。
+
+所以 **A 窗口的写入不会触发 B 窗口的响应式查询**。数据本身是一致的（同一个文件，SQLite 的锁保证了这点），不一致的只是「B 什么时候知道」——B 要等到自己下一次查询才看到新数据。
+
+需要跨窗口实时同步的话，目前得由宿主应用自己广播（例如主进程把 `postChange` 收到的事件转发给其余 `webContents`，各 renderer 收到后主动重查）。
+
+### PGlite：单实例 + 事务 ID
+
+PGlite 的 data directory **不支持两个实例并发打开**，所以 host 按数据目录名做单实例复用：第二个窗口打开同一目录时拿到的是同一个实例，而不是第二份。这既是必需的，也顺带解决了 SQLite 侧那个跨窗口通知问题——`LISTEN` 在实例建立时**一次性**订阅（每会话订一次会让同一条 `NOTIFY` 回调多次），收到通知后扇出给该实例名下的全部会话，于是 **A 窗口的写入会触发 B 窗口的响应式查询**。
+
+代价在事务上：所有事务排队争用那一条连接。`begin` 等不到连接就报 `transaction_unavailable` 而不是无限等待——无限等待会让现场看起来像「数据库不响应」。事务 ID 是随机 UUID 且绑定会话，归属对不上一律 `transaction_not_found`。
+
+窗口崩溃或关闭时，该会话名下所有在途事务被回滚并释放（`releaseOwner` 挂在 `render-process-gone` 与窗口 `destroyed` 上），不留悬挂事务。
+
+#### PGlite host 不要放在主线程
+
+PGlite 的 WASM 在**调用线程上同步**跑完整条查询：实测一条 2 秒的查询把主进程堵了 2007 毫秒——窗口不重绘、菜单不响应、IPC 全排队。「主进程持有单实例」和「主进程不能被堵住」因此无法同时成立，单实例得挪到自己的线程上。
+
+而且要搬就得**整个 host 一起搬**，不能只把 PGlite 放过去：`ElectronPgliteRuntime.transaction` 收的是一个回调，回调过不了线程边界（和它过不了 IPC 边界是同一个原因）。host 搬过去之后，线程边界上流动的就只剩 `DesktopPgliteRequest` / `DesktopPgliteResponse` 这类纯数据。示例见下。
+
+## 完整示例
+
+参考 [dev-rxdb-electron](https://github.com/aiao-io/rxdb/tree/main/apps/dev-rxdb-electron)：
+
+- **SQLite**：`src-electron/desktop-sqlite-bridge.ts`（主进程接线与窗口归属）
+- **PGlite**：`src-electron/desktop-pglite-bridge.ts` + `src-electron/desktop-pglite-worker.ts`——**整个 host 连同 WASM 跑在 worker 线程里**，桥接只做归属记账与转发
+- 两族共用：`src-electron/preload.ts`（桥接暴露）、`src/app/services/desktop-database.service.ts`（renderer 侧使用）
+
+> 三个目录根**必须互不相同**：PGlite 数据目录是一棵会被整体删除/重建的树，把 SQLite 库文件或用户文件混一层进去，一次重建就连带删掉它们。

package/dist/RxDBAdapterElectron.d.ts

@@ -0,0 +1,35 @@
+import { RxDB } from '@aiao/rxdb';
+import { RxDBAdapterSqliteBase } from '@aiao/rxdb-adapter-sqlite-core';
+import { DesktopSqliteClient, DesktopOptions } from '@aiao/rxdb-adapter-sqlite-core/desktop-host';
+import { ADAPTER_NAME } from './electron-adapter.interface.js';
+/**
+ * 把 RxDB 接到 Electron 应用私有目录里的真实 SQLite 文件上。
+ *
+ * @remarks
+ * 数据落在主进程的 `node:sqlite` 连接里，renderer 只通过一条窄传输层发请求，
+ * 因此它既拿不到文件系统句柄，也拿不到物理路径（AC#3）。
+ *
+ * 适配器本身没有自己的查询实现：它复用 {@link RxDBAdapterSqliteBase} 的全套 SQL、事务
+ * 与分支切换逻辑，只把「客户端从哪来」换成了桌面 host。Tauri 侧是同构的另一个类
+ * （`@aiao/rxdb-adapter-tauri` 的 `RxDBAdapterTauri`），两者共用同一份线协议与 renderer client。
+ */
+export declare class RxDBAdapterElectron extends RxDBAdapterSqliteBase {
+    #private;
+    readonly options: DesktopOptions;
+    readonly name: string;
+    /** 解析出的逻辑数据库名，与 host 侧的物理文件一一对应。 */
+    get databaseName(): string;
+    /**
+     * @param rxdb - 绑定的 RxDB 实例
+     * @param options - 传输层与逻辑数据库名
+     * @throws {@link RxDBAdapterDesktopError} 逻辑数据库名越出应用作用域时抛 `invalid_database_name`
+     */
+    constructor(rxdb: RxDB, options?: DesktopOptions);
+    protected createClient(): Promise<DesktopSqliteClient>;
+}
+declare module '@aiao/rxdb' {
+    interface RxDBAdapters {
+        [ADAPTER_NAME]: RxDBAdapterElectron;
+    }
+}
+//# sourceMappingURL=RxDBAdapterElectron.d.ts.map

package/dist/RxDBAdapterElectron.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RxDBAdapterElectron.d.ts","sourceRoot":"","sources":["../src/RxDBAdapterElectron.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,EAEL,mBAAmB,EAGnB,KAAK,cAAc,EACpB,MAAM,6CAA6C,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAE/D;;;;;;;;;;GAUG;AACH,qBAAa,mBAAoB,SAAQ,qBAAqB;;IAgB1D,QAAQ,CAAC,OAAO,EAAE,cAAc;IAdlC,SAAkB,IAAI,EAAE,MAAM,CAAgB;IAE9C,oCAAoC;IACpC,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED;;;;OAIG;gBAED,IAAI,EAAE,IAAI,EACD,OAAO,GAAE,cAAmB;cAQd,YAAY,IAAI,OAAO,CAAC,mBAAmB,CAAC;CAOtE;AAED,OAAO,QAAQ,YAAY,CAAC;IAC1B,UAAU,YAAY;QACpB,CAAC,YAAY,CAAC,EAAE,mBAAmB,CAAC;KACrC;CACF"}

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

@@ -0,0 +1,23 @@
+/**
+ * Electron 适配器在本包内的身份。
+ *
+ * @remarks
+ * 选项形状与逻辑文件名后缀已下沉到 `@aiao/rxdb-adapter-sqlite-core/desktop-host`
+ * （两个桌面运行时共用同一份）；留在这里的只有**注册名**——它是每个运行时包各自的身份，
+ * 共享层不替它们定名。
+ *
+ * 名字按 `<引擎>-<运行时>` 构成（与 `@aiao/rxdb-adapter-miniprogram` 的
+ * `wa-sqlite-miniprogram` 同构）。它不能只叫 `electron`：US-208 会在同一个运行时上
+ * 再立一个 PGlite 适配器（`pglite-electron`），到时两者都要能同时注册。
+ *
+ * @module electron-adapter.interface
+ */
+/**
+ * 适配器在 `RxDBAdapters` 注册表中的名字。
+ *
+ * @remarks
+ * `satisfies` 把它钉在共享层的登记表上：这个名字改了而 `DESKTOP_HOST_ADAPTER_NAMES` 没跟上，
+ * 是编译错误而不是某个下游在运行期才发现的 `adapter_mismatch`。
+ */
+export declare const ADAPTER_NAME: "sqlite-electron";
+//# sourceMappingURL=electron-adapter.interface.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"electron-adapter.interface.d.ts","sourceRoot":"","sources":["../src/electron-adapter.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,mBAA8D,CAAC"}

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

@@ -0,0 +1,52 @@
+import { DesktopHostFileResponse } from '@aiao/rxdb-adapter-sqlite-core/desktop-host';
+/** {@link createElectronFileHost} 的入参。 */
+export interface ElectronFileHostOptions {
+    /**
+     * 解析文件存储根的物理绝对路径。
+     *
+     * @remarks
+     * 由宿主应用提供，因为只有它知道自己的数据目录（Electron 下通常是
+     * `app.getPath('userData')` 下的一个子目录）。每次请求都会调用它而不是只调一次：
+     * Electron 里 `userData` 在 `app.ready` 之前拿不到，缓存会把「还没准备好」永久固化。
+     */
+    readonly resolveStorageRoot: () => string;
+}
+/** 桌面文件 host 实例。 */
+export interface ElectronFileHost {
+    /**
+     * 处理一条来自 renderer 的文件请求。
+     *
+     * @remarks
+     * **永不 reject**：失败以 `kind: 'error'` 的应答返回。Electron 的 `ipcRenderer.invoke`
+     * 在 reject 时会把错误压平成字符串，自定义错误码随之丢失。
+     *
+     * @param request - 未经校验的请求负载
+     * @returns 协议应答
+     */
+    handle(request: unknown): Promise<DesktopHostFileResponse>;
+    /** 当前打开的会话数，用于诊断与关停检查。 */
+    readonly openSessionCount: number;
+    /**
+     * 当前仍被跟踪的锁名个数，用于诊断。
+     *
+     * @remarks
+     * 锁名是逐文件的：稳态下它应当回到 0，长期只增不减就说明队列没被回收。
+     */
+    readonly trackedLockNameCount: number;
+    /**
+     * 关闭全部会话，通常在应用退出前调用。
+     *
+     * @remarks
+     * 返回的 Promise 落地才意味着未提交写入的临时文件真的从磁盘上消失了。
+     * 调用方（退出钩子）必须等它 —— 不等就等于没清，进程先一步退了。
+     */
+    closeAll(): Promise<void>;
+}
+/**
+ * 创建一个桌面文件 host。
+ *
+ * @param options - host 配置
+ * @returns host 实例
+ */
+export declare function createElectronFileHost(options: ElectronFileHostOptions): ElectronFileHost;
+//# sourceMappingURL=electron-file-host.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"electron-file-host.d.ts","sourceRoot":"","sources":["../src/electron-file-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAaL,KAAK,uBAAuB,EAM7B,MAAM,6CAA6C,CAAC;AAkBrD,0CAA0C;AAC1C,MAAM,WAAW,uBAAuB;IACtC;;;;;;;OAOG;IACH,QAAQ,CAAC,kBAAkB,EAAE,MAAM,MAAM,CAAC;CAC3C;AAED,oBAAoB;AACpB,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;OASG;IACH,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAC3D,0BAA0B;IAC1B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC;;;;;;OAMG;IACH,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AA0MD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,uBAAuB,GAAG,gBAAgB,CAmczF"}

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

@@ -0,0 +1,65 @@
+import { DesktopHostChangeEventMessage, DesktopHostResponse } from '@aiao/rxdb-adapter-sqlite-core/desktop-host';
+/** {@link createElectronSqliteHost} 的入参。 */
+export interface ElectronSqliteHostOptions {
+    /**
+     * 把逻辑数据库名解析成物理绝对路径。
+     *
+     * @remarks
+     * 由宿主应用提供，因为只有它知道自己的数据目录（Electron 下通常是
+     * `app.getPath('userData')`）。传进来的名字已经过白名单校验，不含任何路径分隔符，
+     * 因此 `join(root, databaseName)` 不可能越出 `root`。
+     */
+    readonly resolveDatabasePath: (databaseName: string) => string;
+    /** 把变更事件送达对应会话的 renderer，例如 `webContents.send`。 */
+    readonly postChange: (message: DesktopHostChangeEventMessage) => void;
+    /**
+     * 变更事件送达失败时的上报口。
+     *
+     * @remarks
+     * 窗口在写入途中被销毁是常规竞态，此时写入已经落库；若把送达失败当成写失败回给调用方，
+     * 它会重试一次已经成功的写入，产生重复数据。所以送达是 best-effort，失败只上报不影响写结果。
+     * 不传则丢弃——但那意味着这类竞态在日志里完全无痕，建议显式接上。
+     */
+    readonly onDeliveryError?: (error: unknown) => void;
+    /** SQLite page cache 大小（KB）。 */
+    readonly cacheSizeKb?: number;
+    /**
+     * 开事务时撞上另一个连接的锁后，重试多久才放弃（毫秒），默认
+     * {@link DEFAULT_BUSY_RETRY_BUDGET_MS}。
+     *
+     * @remarks
+     * 主要留给测试收窄等待；生产上调它意味着你对「对方最长持锁多久」有更准的判断。
+     */
+    readonly busyRetryBudgetMs?: number;
+}
+/** 桌面 SQLite host 实例。 */
+export interface ElectronSqliteHost {
+    /**
+     * 处理一条来自 renderer 的请求。
+     *
+     * @remarks
+     * **永不 reject**：失败以 `kind: 'error'` 的应答返回。Electron 的 `ipcRenderer.invoke`
+     * 在 reject 时会把错误压平成字符串，自定义错误码随之丢失。
+     *
+     * @param request - 未经校验的请求负载
+     * @returns 协议应答
+     */
+    handle(request: unknown): Promise<DesktopHostResponse>;
+    /** 当前打开的会话数，用于诊断与关停检查。 */
+    readonly openSessionCount: number;
+    /** 关闭全部会话，通常在应用退出前调用。 */
+    closeAll(): void;
+}
+/**
+ * 创建一个桌面 SQLite host。
+ *
+ * @remarks
+ * 每个 `open` 请求得到**独立的** `DatabaseSync` 连接，而不是共享一条：
+ * 多个窗口共用连接时它们的 `BEGIN` 块会互相穿插，事务隔离直接失效。
+ * 各持连接后，跨窗口并发交由 SQLite 自己的文件锁处理（AC#5）。
+ *
+ * @param options - host 配置
+ * @returns host 实例
+ */
+export declare function createElectronSqliteHost(options: ElectronSqliteHostOptions): ElectronSqliteHost;
+//# sourceMappingURL=electron-sqlite-host.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"electron-sqlite-host.d.ts","sourceRoot":"","sources":["../src/electron-sqlite-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAIL,KAAK,6BAA6B,EAElC,KAAK,mBAAmB,EACzB,MAAM,6CAA6C,CAAC;AAmDrD,4CAA4C;AAC5C,MAAM,WAAW,yBAAyB;IACxC;;;;;;;OAOG;IACH,QAAQ,CAAC,mBAAmB,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,MAAM,CAAC;IAC/D,mDAAmD;IACnD,QAAQ,CAAC,UAAU,EAAE,CAAC,OAAO,EAAE,6BAA6B,KAAK,IAAI,CAAC;IACtE;;;;;;;OAOG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACpD,gCAAgC;IAChC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;OAMG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AAED,yBAAyB;AACzB,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;;OASG;IACH,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACvD,0BAA0B;IAC1B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,yBAAyB;IACzB,QAAQ,IAAI,IAAI,CAAC;CAClB;AA4BD;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,yBAAyB,GAAG,kBAAkB,CA0I/F"}

package/dist/host.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `@aiao/rxdb-adapter-electron` 的**特权侧**入口。
+ *
+ * @remarks
+ * 本入口引用 `node:sqlite`，只能在有 Node 运行时的地方加载——Electron 主进程，
+ * 或它自己拥有的 `worker_threads` worker。**不要**把它打进 renderer bundle：
+ * 那等于把文件系统能力还给了渲染进程，AC#3 的隔离随之作废。
+ *
+ * renderer 侧请用 `@aiao/rxdb-adapter-electron`。
+ *
+ * @module @aiao/rxdb-adapter-electron/host
+ */
+export { createElectronSqliteHost, type ElectronSqliteHost, type ElectronSqliteHostOptions } from './electron-sqlite-host.js';
+export { createElectronFileHost, type ElectronFileHost, type ElectronFileHostOptions } from './electron-file-host.js';
+export { NodeSqliteEngine, type NodeSqliteEngineOptions } from './node-sqlite-engine.js';
+export { RxDBAdapterDesktopError, type RxDBAdapterDesktopErrorCode } 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, isDesktopHostFileRequestKind, parseDesktopHostFileRequest, parseDesktopHostRequest, type DesktopHostChangeEventMessage, type DesktopHostCloseRequest, type DesktopHostExecuteRequest, type DesktopHostFileEntry, 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=host.d.ts.map

package/dist/host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../src/host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,wBAAwB,EACxB,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC/B,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAAE,sBAAsB,EAAE,KAAK,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAEtH,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAKzF,OAAO,EAAE,uBAAuB,EAAE,KAAK,2BAA2B,EAAE,MAAM,6CAA6C,CAAC;AAExH,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,4BAA4B,EAC5B,2BAA2B,EAC3B,uBAAuB,EACvB,KAAK,6BAA6B,EAClC,KAAK,uBAAuB,EAC5B,KAAK,yBAAyB,EAC9B,KAAK,oBAAoB,EACzB,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"}