cross-sqlite-client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ueaner
+
+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

@@ -0,0 +1,344 @@
+# cross-sqlite-client
+
+Cross-platform (Web + Tauri) SQLite client for JavaScript/TypeScript apps: one
+`DbClient` interface, a versioned migration framework, and React bindings —
+with no business schema baked in. You bring your own schema and pick an
+adapter; the library handles the platform differences underneath.
+
+## Why
+
+Web (via `@sqlite.org/sqlite-wasm`) and Tauri (via `@tauri-apps/plugin-sql`)
+talk to SQLite in very different ways — different APIs, different connection
+models, different failure modes. This package hides that behind one small
+interface so the rest of your app can call `select()`/`execute()` without
+caring which platform it's running on, and ships a migration runner and React
+context on top so you don't have to write that plumbing per project.
+
+## Install
+
+```bash
+pnpm add cross-sqlite-client
+```
+
+`@sqlite.org/sqlite-wasm` and `@tauri-apps/plugin-sql` are `optionalDependencies`
+of this package, so installing `cross-sqlite-client` pulls both in automatically
+— you don't need to `pnpm add` either one yourself in your app's own
+`package.json`. "optional" here means a failed install of one won't block the
+rest, not "skipped unless requested." Your app only needs to *use* the one
+matching its target platform; remove the other with `--no-optional` (or your
+package manager's equivalent) if you don't want it in `node_modules` at all.
+`react` is an optional peer dependency, needed only if you use the `./react`
+subpath.
+
+## Quick start
+
+**1. Define your schema as versioned migrations** (see [Writing migrations](#writing-migrations)):
+
+```ts
+// appMigrations.ts
+import type { Migration } from "cross-sqlite-client";
+
+export const APP_MIGRATIONS: Migration[] = [
+  {
+    version: 1,
+    statements: [`CREATE TABLE IF NOT EXISTS todos (id INTEGER PRIMARY KEY, title TEXT NOT NULL);`],
+  },
+];
+```
+
+**2. Create a client, picking the adapter for the current platform:**
+
+```ts
+// appDb.ts
+import { createDbClient } from "cross-sqlite-client";
+import { createWebAdapter } from "cross-sqlite-client/adapters/web";
+import { createTauriAdapter } from "cross-sqlite-client/adapters/tauri";
+import { isTauri } from "@tauri-apps/api/core";
+import { APP_MIGRATIONS } from "./appMigrations";
+
+export const clientPromise = createDbClient({
+  name: "my-app", // becomes the OPFS/Tauri database filename
+  adapter: isTauri() ? createTauriAdapter() : createWebAdapter(),
+  migrations: APP_MIGRATIONS,
+});
+```
+
+**3. Make it available to your React tree:**
+
+```tsx
+import { DatabaseProvider } from "cross-sqlite-client/react";
+import { clientPromise } from "./appDb";
+
+function App() {
+  return (
+    <DatabaseProvider client={clientPromise}>
+      <Router />
+    </DatabaseProvider>
+  );
+}
+```
+
+**4. Read it wherever you need the client:**
+
+```tsx
+import { useDatabase } from "cross-sqlite-client/react";
+
+function TodoList() {
+  const { dbClient, isDbReady, isLoading, dbError } = useDatabase();
+
+  if (isLoading) return <Spinner />;
+  if (dbError) return <ErrorMessage error={dbError} />;
+  if (!isDbReady || !dbClient) return null;
+
+  // dbClient.select<T>(sql, params?) / dbClient.execute(sql, params?) / dbClient.close()
+  // ...
+}
+```
+
+## API reference
+
+### Core (`cross-sqlite-client`)
+
+| Export | What it is |
+|---|---|
+| `createDbClient(options)` | Resolves the adapter, initializes it, runs pending migrations, returns `Promise<DbClient>`. |
+| `runMigrations(db, migrations, options?)` | The migration runner `createDbClient` uses internally — call it directly if you're not going through `createDbClient`. |
+| `defaultExecutor` | The migration executor used when `migrationOptions.executor` isn't set — runs each statement with no transaction. |
+| `DbClient` (type) | `{ select<T>(sql, params?), execute(sql, params?), close() }` — see below. |
+| `DbAdapter` / `DbAdapterConfig` (types) | The interface each `createXAdapter()` factory returns / the `{ name }` config passed to `initialize()`. |
+| `Migration` / `MigrationExecutor` / `MigrationOptions` (types) | See [Writing migrations](#writing-migrations). |
+| `DbError` and subclasses | See [Errors](#errors). |
+
+```ts
+import { createDbClient, runMigrations, defaultExecutor } from "cross-sqlite-client";
+```
+
+`DbClient`, the interface every adapter implements:
+
+```ts
+interface DbClient {
+  select<T>(sql: string, params?: unknown[]): Promise<T[]>;
+  execute(sql: string, params?: unknown[]): Promise<{ lastInsertId?: number; rowsAffected?: number }>;
+  close(): Promise<void>;
+}
+```
+
+### Adapters
+
+Each `createXAdapter()` call returns a fresh, independent `DbAdapter` instance
+(no shared module-level state), so you can safely create more than one in the
+same process — e.g. in tests.
+
+| Subpath | Factory | Backing driver | `singleConnection` |
+|---|---|---|---|
+| `cross-sqlite-client/adapters/web` | `createWebAdapter(options?)` | `@sqlite.org/sqlite-wasm` (Worker) | `true` |
+| `cross-sqlite-client/adapters/tauri` | `createTauriAdapter()` | `@tauri-apps/plugin-sql` | `false` |
+| `cross-sqlite-client/adapters/memory` | `createMemoryAdapter()` | `@sqlite.org/sqlite-wasm` (Node/main-thread, in-memory) | `true` |
+
+`singleConnection` says whether every `execute()`/`select()` call on that
+adapter is guaranteed to land on the same physical connection — see
+[Custom migration executors](#custom-migration-executors-and-singleconnection)
+for why that matters.
+
+**`createWebAdapter(options?)`:**
+
+| Option | Default | Meaning |
+|---|---|---|
+| `timeoutMs` | `15000` | How long to wait for the SQLite worker to become ready before `initialize()` rejects. Without this, a failed worker-script load would leave `initialize()` pending forever. |
+| `fallbackToMemory` | `true` | Whether to silently use `:memory:` when OPFS isn't available, instead of throwing. See [COOP/COEP](#coopcoep-required-for-opfs-persistence). |
+| `singleTabLock` | `true` | Whether to coordinate access to the same OPFS file across browser tabs. See [Multi-tab coordination](#multi-tab-coordination). |
+
+**`createTauriAdapter()`** and **`createMemoryAdapter()`** take no options.
+`createMemoryAdapter()` is meant for tests — see [Testing](#testing).
+
+### React (`cross-sqlite-client/react`)
+
+| Export | What it is |
+|---|---|
+| `<DatabaseProvider client={...}>` | Takes a `DbClient` or `Promise<DbClient>` (typically `createDbClient()`'s return value) and resolves it, exposing the result via context. It does **not** decide which adapter/migrations to use — that's your app's job (see Quick start) — and it does **not** call `client.close()` on unmount (see below). |
+| `useDatabase()` | Reads the context: `{ dbClient, isDbReady, isLoading, dbError }`. Throws if called outside a `DatabaseProvider`. |
+
+Two things worth knowing about `DatabaseProvider`:
+
+- **No `retry`.** The `client` prop only ever settles once — retrying means
+  passing it a *new* promise, which re-triggers initialization because the
+  prop reference changed:
+
+  ```tsx
+  function App() {
+    const [clientPromise, setClientPromise] = useState(() => createDbClient({ ... }));
+
+    return (
+      <DatabaseProvider client={clientPromise}>
+        {/* on a dbError, e.g. from a "Retry" button: */}
+        {/* setClientPromise(createDbClient({ ... })) */}
+        <Router />
+      </DatabaseProvider>
+    );
+  }
+  ```
+
+- **No auto-`close()` on unmount.** Whoever creates the client owns closing
+  it. If `DatabaseProvider` closed it automatically, a cached/shared client
+  (e.g. an app-level singleton) would get closed the moment the provider
+  happens to unmount and remount (conditional rendering, a remounting route,
+  test setup/teardown) — leaving `isDbReady: true` pointing at a dead
+  connection. Close the client yourself, in whatever code created it, if its
+  lifetime should be tied to something specific.
+
+## Writing migrations
+
+```ts
+interface Migration {
+  version: number;
+  statements: string[]; // plain DDL/DML strings, no bound parameters
+}
+```
+
+- **Versions must start at 1.** With no migrations applied yet, `runMigrations`
+  treats the current version as `0`; a migration with `version: 0` would never
+  satisfy `version > currentVersion` and would be silently skipped forever.
+  `runMigrations` throws immediately if any `version <= 0`.
+- **Every statement must be safe to re-run.** There is no cross-platform
+  transaction guarantee (see below), so if a migration fails partway, the next
+  startup re-runs the *entire* version from scratch. Stick to
+  `CREATE TABLE/INDEX IF NOT EXISTS` for new schema. For a future
+  non-idempotent change (e.g. renaming a column), check the current schema
+  state first — e.g. `SELECT 1 FROM pragma_table_info('t') WHERE name = '...'`
+  — and skip the step if it's already done, rather than relying on rollback.
+
+## Custom migration executors and `singleConnection`
+
+The default executor (`defaultExecutor`) runs each migration statement
+independently, with no transaction. `adapters/web` also exports a
+`transactionalExecutor` that wraps a migration in `BEGIN`/`COMMIT`/`ROLLBACK` —
+but that's only safe on an adapter whose `singleConnection` is `true` (a real,
+single persistent connection). `@tauri-apps/plugin-sql`'s backend is a
+connection pool (`sqlx::Pool<Sqlite>`); separate `execute()` calls aren't
+guaranteed to land on the same physical connection, so a `BEGIN` and `COMMIT`
+split across calls can be silently torn apart there without any error.
+`createDbClient()` throws up front if you pass an executor marked
+`requiresSingleConnection: true` to an adapter whose `singleConnection` is
+`false`.
+
+`transactionalExecutor` carries that marker via
+`Object.assign(fn, { requiresSingleConnection: true })` — not by comparing the
+executor to `defaultExecutor` by reference, which would only catch "some
+non-default executor was passed," not specifically "this executor needs a
+transaction." Write your own executor the same way if it also manages a
+transaction. An executor that doesn't touch transactions at all (e.g. one
+that just adds logging) doesn't need the marker and won't be rejected, even on
+a pooled-connection adapter.
+
+```ts
+import { runMigrations } from "cross-sqlite-client";
+import { transactionalExecutor } from "cross-sqlite-client/adapters/web";
+
+await runMigrations(client, APP_MIGRATIONS, { executor: transactionalExecutor });
+```
+
+## Web adapter details
+
+### COOP/COEP required for OPFS persistence
+
+OPFS persistence (used by `createWebAdapter()`) requires the page to be served
+with:
+
+```
+Cross-Origin-Opener-Policy: same-origin
+Cross-Origin-Embedder-Policy: require-corp
+```
+
+Without these headers, the adapter doesn't error — it silently falls back to
+an in-memory database (`fallbackToMemory: true` by default), so data won't
+survive a page reload. Pass `fallbackToMemory: false` if you'd rather fail
+loudly than run in-memory unexpectedly.
+
+Note this is a *deployment* constraint, not a browser-version one: even on a
+fully modern browser, you can lose cross-origin isolation by being embedded in
+someone else's iframe, being hosted on a platform that won't let you set
+custom headers, or a team deliberately not enabling `COEP: require-corp`
+because it would block some other third-party script on the same page.
+There's currently no middle tier between full OPFS persistence and no
+persistence at all (e.g. a `localStorage`-backed fallback) — see
+[Known limitations](#known-limitations).
+
+### Multi-tab coordination
+
+sqlite-wasm's `opfs` VFS has its own locking protocol, so two tabs writing to
+the same OPFS-backed file won't corrupt data and generally won't hang — the
+losing tab just gets a catchable "database is locked" SQL error. But that
+error only surfaces the moment some query happens to hit contention, with
+nothing telling you *why* it failed.
+
+By default (`singleTabLock: true`), `createWebAdapter()` uses the
+[Web Locks API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Locks_API)
+to claim a named lock for the database file before opening it. If another tab
+already holds it, `initialize()` rejects immediately with `DbTabLockError`
+instead of letting the app find out later via a random query failure — catch
+it to show something like "this app is already open in another tab." Pass
+`singleTabLock: false` to skip this and rely solely on sqlite-wasm's own
+retry/`SQLITE_BUSY` behavior. This only ever applies to the OPFS-backed path —
+`:memory:` is private per tab, so there's nothing to coordinate there.
+
+## Errors
+
+Every adapter throws one of these (all extend `DbError extends Error`, and all
+accept an optional `cause`):
+
+| Class | Thrown when |
+|---|---|
+| `DbError` | Generic/usage errors, e.g. calling `select()`/`execute()` before `initialize()` resolves, or after `close()`. |
+| `DbInitializationError` | `adapter.initialize()` failed (worker/OPFS/Tauri-load failure, etc.). |
+| `DbExecutionError` (has `.sql` and `.params`) | A `select()`/`execute()` call failed. |
+| `DbCloseError` | `client.close()` failed. |
+| `DbTabLockError` | (Web adapter only, `singleTabLock: true`) Another tab already holds the database. |
+
+```ts
+import { DbTabLockError } from "cross-sqlite-client";
+
+try {
+  await clientPromise;
+} catch (error) {
+  if (error instanceof DbTabLockError) {
+    // show "already open in another tab" instead of a generic error
+  }
+}
+```
+
+## Testing
+
+Use `createMemoryAdapter()` in tests instead of mocking `DbClient` — it's a
+real SQLite engine (the same one the web adapter uses, via
+`@sqlite.org/sqlite-wasm`'s Node/main-thread build), so your SQL runs for
+real and behaves the same as it would against the web adapter, just without
+persistence:
+
+```ts
+import { createMemoryAdapter } from "cross-sqlite-client/adapters/memory";
+import { runMigrations } from "cross-sqlite-client";
+
+const client = await createMemoryAdapter().initialize({ name: "test" });
+await runMigrations(client, APP_MIGRATIONS);
+// exercise client.select() / client.execute() as usual
+```
+
+Each `createMemoryAdapter()` call is a fresh, independent instance, so
+separate tests (or parallel tests in the same process) don't share state.
+
+## Known limitations
+
+- **`lastInsertId` precision.** `DbClient.execute()`'s `lastInsertId` is typed
+  as `number`. The web adapter converts SQLite's `sqlite3_last_insert_rowid()`
+  (a 64-bit `bigint`, up to 2^63-1) down via `Number()`, so a rowid beyond
+  `Number.MAX_SAFE_INTEGER` (2^53-1) loses precision. Not an issue for a
+  typical local-first app (that's over 9 quadrillion rows in one table), but
+  if you need an exact large rowid, read it back with a dedicated
+  `SELECT last_insert_rowid()` query instead.
+- **No OPFS degradation tier.** When OPFS/cross-origin isolation isn't
+  available, `createWebAdapter()` only has two states: full OPFS persistence,
+  or `:memory:` with none at all. sqlite-wasm ships a `kvvfs` backend
+  (`localStorage`/`sessionStorage`-based, no cross-origin isolation required)
+  that could serve as a middle tier, but it wasn't wired in as of this
+  writing — pursue it if you need persistence in deployments that can't
+  achieve cross-origin isolation (see [COOP/COEP](#coopcoep-required-for-opfs-persistence)).

package/README.zh-CN.md

@@ -0,0 +1,246 @@
+# cross-sqlite-client
+
+面向 JavaScript/TypeScript 应用的跨平台（Web + Tauri）SQLite 客户端：一个统一的 `DbClient` 接口、版本化迁移框架、以及 React 绑定——业务 schema 完全由调用方定义。你提供自己的 schema 并选一个适配器，库负责抹平底层平台差异。
+
+## 为什么需要它
+
+Web（通过 `@sqlite.org/sqlite-wasm`）和 Tauri（通过 `@tauri-apps/plugin-sql`）访问 SQLite 的方式截然不同：API 不同、连接模型不同、失败模式也不同。这个库把这些差异隐藏在一个很小的接口后面，让应用其余部分直接调用 `select()`/`execute()`，而不用关心自己跑在哪个平台上；同时内置了迁移运行器和 React Context，省得每个项目都重复写一遍。
+
+## 安装
+
+```bash
+pnpm add cross-sqlite-client
+```
+
+`@sqlite.org/sqlite-wasm` 和 `@tauri-apps/plugin-sql` 是本包的 `optionalDependencies`，因此安装 `cross-sqlite-client` 时会自动把两个都带上——不需要在你自己应用的 `package.json` 里单独 `pnpm add` 它们。这里的 optional 意味着其中一个安装失败不会阻塞其余安装，而不是「按需跳过」。你的应用只需要**使用**匹配目标平台的那一个；如果不想让另一个出现在 `node_modules` 里，可用 `--no-optional`（或对应包管理器的等效参数）安装。`react` 是可选 peer dependency，只有使用 `./react` 子路径时才需要。
+
+## 快速开始
+
+**1. 用版本化迁移定义 schema**（详见[编写迁移](#编写迁移)）：
+
+```ts
+// appMigrations.ts
+import type { Migration } from "cross-sqlite-client";
+
+export const APP_MIGRATIONS: Migration[] = [
+  {
+    version: 1,
+    statements: [`CREATE TABLE IF NOT EXISTS todos (id INTEGER PRIMARY KEY, title TEXT NOT NULL);`],
+  },
+];
+```
+
+**2. 创建客户端，按当前平台选择适配器：**
+
+```ts
+// appDb.ts
+import { createDbClient } from "cross-sqlite-client";
+import { createWebAdapter } from "cross-sqlite-client/adapters/web";
+import { createTauriAdapter } from "cross-sqlite-client/adapters/tauri";
+import { isTauri } from "@tauri-apps/api/core";
+import { APP_MIGRATIONS } from "./appMigrations";
+
+export const clientPromise = createDbClient({
+  name: "my-app", // 会成为 OPFS/Tauri 数据库文件名
+  adapter: isTauri() ? createTauriAdapter() : createWebAdapter(),
+  migrations: APP_MIGRATIONS,
+});
+```
+
+**3. 通过 React Provider 提供给组件树：**
+
+```tsx
+import { DatabaseProvider } from "cross-sqlite-client/react";
+import { clientPromise } from "./appDb";
+
+function App() {
+  return (
+    <DatabaseProvider client={clientPromise}>
+      <Router />
+    </DatabaseProvider>
+  );
+}
+```
+
+**4. 在任意组件里读取客户端：**
+
+```tsx
+import { useDatabase } from "cross-sqlite-client/react";
+
+function TodoList() {
+  const { dbClient, isDbReady, isLoading, dbError } = useDatabase();
+
+  if (isLoading) return <Spinner />;
+  if (dbError) return <ErrorMessage error={dbError} />;
+  if (!isDbReady || !dbClient) return null;
+
+  // dbClient.select<T>(sql, params?) / dbClient.execute(sql, params?) / dbClient.close()
+  // ...
+}
+```
+
+## API 参考
+
+### 核心（`cross-sqlite-client`）
+
+| 导出 | 说明 |
+|---|---|
+| `createDbClient(options)` | 初始化适配器、执行待应用迁移，返回 `Promise<DbClient>`。 |
+| `runMigrations(db, migrations, options?)` | `createDbClient` 内部使用的迁移运行器；不经过 `createDbClient` 时可直接调用。 |
+| `defaultExecutor` | 未设置 `migrationOptions.executor` 时使用的默认迁移执行器：逐条执行语句，无事务包裹。 |
+| `DbClient`（类型） | `{ select<T>(sql, params?), execute(sql, params?), close() }` —— 详见下文。 |
+| `DbAdapter` / `DbAdapterConfig`（类型） | 各 `createXAdapter()` 工厂返回的接口 / 传给 `initialize()` 的 `{ name }` 配置。 |
+| `Migration` / `MigrationExecutor` / `MigrationOptions`（类型） | 见[编写迁移](#编写迁移)。 |
+| `DbError` 及子类 | 见[错误](#错误)。 |
+
+```ts
+import { createDbClient, runMigrations, defaultExecutor } from "cross-sqlite-client";
+```
+
+每个适配器都实现的 `DbClient` 接口：
+
+```ts
+interface DbClient {
+  select<T>(sql: string, params?: unknown[]): Promise<T[]>;
+  execute(sql: string, params?: unknown[]): Promise<{ lastInsertId?: number; rowsAffected?: number }>;
+  close(): Promise<void>;
+}
+```
+
+### 适配器
+
+每次调用 `createXAdapter()` 都会返回一个**全新的、相互独立的** `DbAdapter` 实例（没有模块级单例状态），因此同一进程里可以放心创建多个——例如测试里。
+
+| 子路径 | 工厂 | 底层驱动 | `singleConnection` |
+|---|---|---|---|
+| `cross-sqlite-client/adapters/web` | `createWebAdapter(options?)` | `@sqlite.org/sqlite-wasm`（Worker） | `true` |
+| `cross-sqlite-client/adapters/tauri` | `createTauriAdapter()` | `@tauri-apps/plugin-sql` | `false` |
+| `cross-sqlite-client/adapters/memory` | `createMemoryAdapter()` | `@sqlite.org/sqlite-wasm`（Node/主线程，内存） | `true` |
+
+`singleConnection` 表示该适配器的每次 `execute()`/`select()` 是否保证落在同一条物理连接上——为什么重要，见[自定义迁移执行器](#自定义迁移执行器与-singleconnection)。
+
+**`createWebAdapter(options?)` 选项：**
+
+| 选项 | 默认值 | 说明 |
+|---|---|---|
+| `timeoutMs` | `15000` | 等待 SQLite Worker 就绪的超时时间；若 Worker 脚本加载失败，不设超时会让 `initialize()` 永远 pending。 |
+| `fallbackToMemory` | `true` | OPFS 不可用时是否静默回退到 `:memory:`，而不是抛错。详见 [COOP/COEP](#opfs-持久化需要-coopcoep)。 |
+| `singleTabLock` | `true` | 是否跨浏览器标签页协调对同一 OPFS 文件的访问。详见[多标签页协调](#多标签页协调)。 |
+
+**`createTauriAdapter()`** 和 **`createMemoryAdapter()`** 不接受选项。`createMemoryAdapter()` 用于测试——见[测试](#测试)。
+
+### React（`cross-sqlite-client/react`）
+
+| 导出 | 说明 |
+|---|---|
+| `<DatabaseProvider client={...}>` | 接收 `DbClient` 或 `Promise<DbClient>`（通常是 `createDbClient()` 的返回值），解析后通过 Context 暴露。它**不**决定用哪个适配器或迁移哪些 schema——那是应用层的职责（见快速开始）——也**不**在卸载时调用 `client.close()`（原因见下文）。 |
+| `useDatabase()` | 读取 Context：`{ dbClient, isDbReady, isLoading, dbError }`。在 `DatabaseProvider` 外调用会抛错。 |
+
+关于 `DatabaseProvider` 有两点值得注意：
+
+- **没有内置 `retry`。** `client` prop 只会进入最终状态一次——重试意味着传给它一个**新的 Promise**，prop 引用变化会重新触发初始化：
+
+  ```tsx
+  function App() {
+    const [clientPromise, setClientPromise] = useState(() => createDbClient({ ... }));
+
+    return (
+      <DatabaseProvider client={clientPromise}>
+        {/* 出现 dbError 时，例如点击「重试」按钮：setClientPromise(createDbClient({ ... })) */}
+        <Router />
+      </DatabaseProvider>
+    );
+  }
+  ```
+
+- **卸载时不自动 `close()`。** 谁创建 client，谁负责关闭。如果 `DatabaseProvider` 自动关闭 client，那么当它因为条件渲染、路由重挂载、测试 setup/teardown 而卸载又重新挂载时，被缓存/共享的 client（比如应用级单例）就会被直接关掉——结果 `isDbReady: true`，但连接其实已经死了。如果 client 生命周期需要绑定到某个特定范围，请在你创建它的地方自行关闭。
+
+## 编写迁移
+
+```ts
+interface Migration {
+  version: number;
+  statements: string[]; // 纯 DDL/DML 字符串，不带绑定参数
+}
+```
+
+- **版本号必须从 1 开始。** 没有应用任何迁移时，`runMigrations` 把当前版本视为 `0`；一个 `version: 0` 的迁移永远满足不了 `version > currentVersion`，会被永久静默跳过。`runMigrations` 会在传入 `version <= 0` 时立即抛错。
+- **每条语句都必须可安全重跑。** 跨平台事务没有统一保证（原因见下文），因此如果某次迁移执行到一半失败，下次启动会**从头重跑整个 version**。新 schema 请使用 `CREATE TABLE/INDEX IF NOT EXISTS`。未来若要写不可重跑的操作（例如重命名列），先查询当前 schema 状态——例如 `SELECT 1 FROM pragma_table_info('t') WHERE name = '...'`——已完成就跳过，而不是依赖回滚。
+
+## 自定义迁移执行器与 `singleConnection`
+
+默认执行器（`defaultExecutor`）逐条独立执行迁移语句，无事务包裹。`adapters/web` 还导出了 `transactionalExecutor`，它把一次迁移包在 `BEGIN`/`COMMIT`/`ROLLBACK` 里——但这只在 `singleConnection: true` 的适配器上安全（真正的一条持久连接）。`@tauri-apps/plugin-sql` 的底层是连接池（`sqlx::Pool<Sqlite>`），多次 `execute()` 调用不保证落在同一条物理连接上，`BEGIN` 和 `COMMIT` 跨调用拆散后甚至可能不报错。`createDbClient()` 会在你把一个标记为 `requiresSingleConnection: true` 的执行器传给 `singleConnection: false` 的适配器时，提前抛错。
+
+这个检查基于显式标记，而不是把执行器和 `defaultExecutor` 做引用相等比较：`transactionalExecutor` 通过 `Object.assign(fn, { requiresSingleConnection: true })` 携带标记。如果你也写了一个管理事务的自定义执行器，请用同样方式标记。完全不碰事务的执行器（例如只加日志）不需要这个标记，即使传给连接池适配器也不会被拒绝。
+
+```ts
+import { runMigrations } from "cross-sqlite-client";
+import { transactionalExecutor } from "cross-sqlite-client/adapters/web";
+
+await runMigrations(client, APP_MIGRATIONS, { executor: transactionalExecutor });
+```
+
+## Web 适配器细节
+
+### OPFS 持久化需要 COOP/COEP
+
+`createWebAdapter()` 使用 OPFS 持久化，要求页面必须以下列响应头提供：
+
+```
+Cross-Origin-Opener-Policy: same-origin
+Cross-Origin-Embedder-Policy: require-corp
+```
+
+没有这些头时，适配器不会报错，而是静默回退到内存数据库（`fallbackToMemory: true` 为默认），因此页面刷新后数据会丢失。如果你宁可失败也不愿在不知情的情况下跑内存模式，可传 `fallbackToMemory: false`。
+
+注意这是**部署/托管层面的约束**，不是浏览器版本问题：即使在很新的浏览器上，也可能因为嵌在别人的 iframe 里、托管平台不允许自定义响应头、或者团队故意不启用 `COEP: require-corp`（以免阻塞页面上的其他第三方脚本）而失去跨源隔离。目前只在「完整 OPFS 持久化」和「完全没有持久化（`:memory:`）」之间二选一——例如 sqlite-wasm 还提供了基于 `localStorage`/`sessionStorage` 的 `kvvfs` 后端，可作为中间层，但当前版本尚未接入；见[已知限制](#已知限制)。
+
+### 多标签页协调
+
+sqlite-wasm 的 `opfs` VFS 自带锁协议，因此两个标签页同时写同一个 OPFS 文件时**不会损坏数据，通常也不会卡死**——失败的标签页会收到一个可捕获的 "database is locked" SQL 错误。但这个错误只在某条查询恰好撞上竞争时才暴露，而且不会告诉你**为什么**失败。
+
+默认开启 `singleTabLock: true` 时，`createWebAdapter()` 会在打开数据库文件前用 [Web Locks API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Locks_API) 申请一个命名锁。如果另一个标签页已经持有该锁，`initialize()` 会立即以 `DbTabLockError` reject，而不是让应用在之后的某次随机查询里才发现失败——捕获它之后可以展示「该应用已在另一个标签页打开」之类的提示。传 `singleTabLock: false` 可跳过此行为，只依赖 sqlite-wasm 自身的重试/`SQLITE_BUSY` 处理。它只对 OPFS 持久化路径生效——`:memory:` 每个标签页互相独立，无需协调。
+
+## 错误
+
+所有适配器都抛出以下错误类（全部继承 `DbError extends Error`，均可选传入 `cause`）：
+
+| 类 | 触发时机 |
+|---|---|
+| `DbError` | 通用/用法错误，例如 `initialize()` 还没 resolve 就调用 `select()`/`execute()`，或 `close()` 之后调用。 |
+| `DbInitializationError` | `adapter.initialize()` 失败（Worker/OPFS/Tauri 加载失败等）。 |
+| `DbExecutionError`（带 `.sql` 和 `.params`） | `select()`/`execute()` 调用失败。 |
+| `DbCloseError` | `client.close()` 失败。 |
+| `DbTabLockError` | （仅 Web 适配器，`singleTabLock: true`）另一个标签页已持有数据库锁。 |
+
+```ts
+import { DbTabLockError } from "cross-sqlite-client";
+
+try {
+  await clientPromise;
+} catch (error) {
+  if (error instanceof DbTabLockError) {
+    // 展示「已在另一个标签页打开」而不是通用错误
+  }
+}
+```
+
+## 测试
+
+测试时请用 `createMemoryAdapter()`，而不是 mock `DbClient`——它是真正的 SQLite 引擎（与 Web 适配器使用同一个 `@sqlite.org/sqlite-wasm` 的 Node/主线程版本），因此你的 SQL 会真实执行，行为与 Web 适配器一致，只是没有持久化：
+
+```ts
+import { createMemoryAdapter } from "cross-sqlite-client/adapters/memory";
+import { runMigrations } from "cross-sqlite-client";
+
+const client = await createMemoryAdapter().initialize({ name: "test" });
+await runMigrations(client, APP_MIGRATIONS);
+// 正常使用 client.select() / client.execute()
+```
+
+每次 `createMemoryAdapter()` 调用都是一个全新的独立实例，因此不同测试（或同一进程里的并行测试）不会共享状态。
+
+## 已知限制
+
+- **`lastInsertId` 精度。** `DbClient.execute()` 返回的 `lastInsertId` 类型是 `number`。Web 适配器会把 SQLite 的 `sqlite3_last_insert_rowid()`（64 位 `bigint`，最大 2^63-1）通过 `Number()` 转换，因此超过 `Number.MAX_SAFE_INTEGER`（2^53-1）时会丢失精度。对典型本地优先应用不是问题（需要单表超过 9 千万亿行才会触发），但如果你需要精确的大整数 rowid，请用专门的 `SELECT last_insert_rowid()` 查询读取。
+- **没有 OPFS 降级层。** OPFS/跨源隔离不可用时，`createWebAdapter()` 只有两种状态：完整 OPFS 持久化，或完全没有持久化的 `:memory:`。sqlite-wasm 提供了基于 `localStorage`/`sessionStorage` 的 `kvvfs` 后端，可作为中间层，但当前版本尚未接入——如果你需要在无法达到跨源隔离的部署环境里获得持久化，可以考虑接入它（见 [COOP/COEP](#opfs-持久化需要-coopcoep)）。

package/dist/adapters/memory.d.ts

@@ -0,0 +1,12 @@
+import { n as DbAdapter } from "../types-XKvAFU82.js";
+//#region src/adapters/memory.d.ts
+/**
+ * 内存适配器（测试用）。基于 @sqlite.org/sqlite-wasm 官方支持的 Node 单线程用法
+ * （sqlite3InitModule() + oo1.DB(':memory:')），跟 web 适配器共享同一个 sqlite3 引擎，
+ * 保证同一组 SQL 在两个适配器上的行为一致，而不是用另一套假实现模拟。
+ *
+ * 每次调用 createMemoryAdapter() 返回状态独立的新实例，可在同一进程里创建多个互不干扰的
+ * 实例（例如并行测试）。
+ */
+export declare function createMemoryAdapter(): DbAdapter;
+//#endregion

package/dist/adapters/memory.js

@@ -0,0 +1,65 @@
+import { i as DbInitializationError, n as DbError, r as DbExecutionError, t as DbCloseError } from "../errors-D9KnLHTp.js";
+import sqlite3InitModule from "@sqlite.org/sqlite-wasm";
+//#region src/adapters/memory.ts
+/**
+* 内存适配器（测试用）。基于 @sqlite.org/sqlite-wasm 官方支持的 Node 单线程用法
+* （sqlite3InitModule() + oo1.DB(':memory:')），跟 web 适配器共享同一个 sqlite3 引擎，
+* 保证同一组 SQL 在两个适配器上的行为一致，而不是用另一套假实现模拟。
+*
+* 每次调用 createMemoryAdapter() 返回状态独立的新实例，可在同一进程里创建多个互不干扰的
+* 实例（例如并行测试）。
+*/
+function createMemoryAdapter() {
+	let sqlite3 = null;
+	let db = null;
+	const client = {
+		async select(sql, params = []) {
+			if (!db) throw new DbError("[Memory DB] Database not initialized. Call initialize() first.");
+			try {
+				return db.selectObjects(sql, params);
+			} catch (error) {
+				throw new DbExecutionError(sql, params, error);
+			}
+		},
+		async execute(sql, params = []) {
+			if (!db || !sqlite3) throw new DbError("[Memory DB] Database not initialized. Call initialize() first.");
+			try {
+				db.exec({
+					sql,
+					bind: params
+				});
+				const rowsAffected = db.changes(false, false);
+				return {
+					lastInsertId: db.pointer !== void 0 ? Number(sqlite3.capi.sqlite3_last_insert_rowid(db.pointer)) : void 0,
+					rowsAffected
+				};
+			} catch (error) {
+				throw new DbExecutionError(sql, params, error);
+			}
+		},
+		async close() {
+			try {
+				db?.close();
+			} catch (error) {
+				throw new DbCloseError(error);
+			} finally {
+				db = null;
+			}
+		}
+	};
+	return {
+		singleConnection: true,
+		async initialize() {
+			if (db) return client;
+			try {
+				sqlite3 = await sqlite3InitModule();
+				db = new sqlite3.oo1.DB(":memory:", "c");
+				return client;
+			} catch (error) {
+				throw new DbInitializationError(error);
+			}
+		}
+	};
+}
+//#endregion
+export { createMemoryAdapter };

package/dist/adapters/tauri.d.ts

@@ -0,0 +1,11 @@
+import { n as DbAdapter } from "../types-XKvAFU82.js";
+//#region src/adapters/tauri.d.ts
+/**
+ * Tauri (@tauri-apps/plugin-sql) 适配器。每次调用 createTauriAdapter() 返回一个状态独立的
+ * 新实例——db 保存在这个函数的闭包里，不是模块级单例。
+ *
+ * singleConnection 为 false：@tauri-apps/plugin-sql 底层是 sqlx::Pool<Sqlite> 连接池，
+ * 每次 execute()/select() 调用独立获取/归还一个物理连接，不保证跨调用落在同一条连接上。
+ */
+export declare function createTauriAdapter(): DbAdapter;
+//#endregion

package/dist/adapters/tauri.js

@@ -0,0 +1,58 @@
+import { i as DbInitializationError, n as DbError, r as DbExecutionError, t as DbCloseError } from "../errors-D9KnLHTp.js";
+import Sqlite from "@tauri-apps/plugin-sql";
+//#region src/adapters/tauri.ts
+/**
+* Tauri (@tauri-apps/plugin-sql) 适配器。每次调用 createTauriAdapter() 返回一个状态独立的
+* 新实例——db 保存在这个函数的闭包里，不是模块级单例。
+*
+* singleConnection 为 false：@tauri-apps/plugin-sql 底层是 sqlx::Pool<Sqlite> 连接池，
+* 每次 execute()/select() 调用独立获取/归还一个物理连接，不保证跨调用落在同一条连接上。
+*/
+function createTauriAdapter() {
+	let db = null;
+	const client = {
+		async select(sql, params = []) {
+			if (!db) throw new DbError("[Tauri DB] Database not initialized. Call initialize() first.");
+			try {
+				return await db.select(sql, params);
+			} catch (error) {
+				throw new DbExecutionError(sql, params, error);
+			}
+		},
+		async execute(sql, params = []) {
+			if (!db) throw new DbError("[Tauri DB] Database not initialized. Call initialize() first.");
+			try {
+				const result = await db.execute(sql, params);
+				return {
+					lastInsertId: result.lastInsertId,
+					rowsAffected: result.rowsAffected
+				};
+			} catch (error) {
+				throw new DbExecutionError(sql, params, error);
+			}
+		},
+		async close() {
+			if (db) try {
+				if (!await db.close()) throw new DbCloseError();
+			} catch (error) {
+				throw error instanceof DbCloseError ? error : new DbCloseError(error);
+			} finally {
+				db = null;
+			}
+		}
+	};
+	return {
+		singleConnection: false,
+		async initialize(config) {
+			if (db) return client;
+			try {
+				db = await Sqlite.load(`sqlite:${config.name}.db`);
+				return client;
+			} catch (error) {
+				throw new DbInitializationError(error);
+			}
+		}
+	};
+}
+//#endregion
+export { createTauriAdapter };

package/dist/adapters/web.d.ts

@@ -0,0 +1,43 @@
+import { n as DbAdapter, o as MigrationExecutor } from "../types-XKvAFU82.js";
+//#region src/adapters/web.d.ts
+export interface WebAdapterOptions {
+  /** 等待 Worker 就绪的超时时间（毫秒），超时后 initialize() 会 reject 而不是永远 pending */
+  timeoutMs?: number;
+  /** OPFS 不可用（不支持/未跨域隔离/初始化失败）时是否静默退化为内存模式，默认 true */
+  fallbackToMemory?: boolean;
+  /**
+   * 用 Web Locks API（navigator.locks）在同一 origin 的多个标签页/窗口之间协调对同一个
+   * OPFS 文件的访问，默认 true。
+   *
+   * 背景：sqlite-wasm 的 opfs VFS 本身有锁协议（xLock/xUnlock 走 SharedArrayBuffer +
+   * Atomics.wait()），两个标签页同时写同一个 OPFS 文件不会挂死或数据损坏，冲突时会重试一段
+   * 时间后返回 SQLITE_BUSY，作为一次普通的、可 catch 的 SQL 错误出现——但这个错误只会在业务
+   * 代码真正执行到某条 SQL 语句时才暴露，且没有任何提示"这是因为别的标签页正在用这个库"。
+   * 启用 singleTabLock 后，initialize() 会在真正打开 OPFS 文件之前先尝试抢一个跨标签页命名
+   * 锁；抢不到（说明另一个标签页已经持有）会立即抛出 DbTabLockError，而不是让业务代码在某次
+   * 随机的查询里才踩到一个语义不明的 SQL 错误。
+   *
+   * 只在真的走 OPFS 持久化时才会用到这把锁——:memory: 每个标签页互相独立，没有需要协调的资源，
+   * 不受这个选项影响。
+   */
+  singleTabLock?: boolean;
+}
+/**
+ * 用 Web Locks API 尝试（不等待）拿到一个跨标签页命名锁。拿不到（另一个标签页已持有）时
+ * resolve 到 null；拿到时返回一个 release() 函数，调用方后续必须调用它来释放锁。
+ *
+ * 实现上依赖一个常见技巧：navigator.locks.request() 的回调函数返回什么 Promise，锁就持有到
+ * 那个 Promise settle 为止；这里让回调返回一个我们自己创建、直到 release() 被调用才会 resolve
+ * 的 Promise，从而把锁"长期持有"而不是只在回调执行期间持有。
+ */
+export declare function tryAcquireTabLock(lockName: string): Promise<(() => void) | null>;
+/**
+ * Web (sqlite-wasm) 适配器。每次调用 createWebAdapter() 返回一个状态独立的新实例——
+ * promiser/dbId 保存在这个函数的闭包里，不是模块级单例，允许同一进程里存在多个互不干扰的
+ * 实例（例如测试）。
+ */
+export declare function createWebAdapter(options?: WebAdapterOptions): DbAdapter;
+export declare const transactionalExecutor: MigrationExecutor & {
+  requiresSingleConnection: true;
+};
+//#endregion

package/dist/adapters/web.js

@@ -0,0 +1,154 @@
+import { a as DbTabLockError, i as DbInitializationError, n as DbError, r as DbExecutionError, t as DbCloseError } from "../errors-D9KnLHTp.js";
+import { sqlite3Worker1Promiser } from "@sqlite.org/sqlite-wasm";
+//#region src/adapters/web.ts
+const DEFAULT_TIMEOUT_MS = 15e3;
+/**
+* 用 Web Locks API 尝试（不等待）拿到一个跨标签页命名锁。拿不到（另一个标签页已持有）时
+* resolve 到 null；拿到时返回一个 release() 函数，调用方后续必须调用它来释放锁。
+*
+* 实现上依赖一个常见技巧：navigator.locks.request() 的回调函数返回什么 Promise，锁就持有到
+* 那个 Promise settle 为止；这里让回调返回一个我们自己创建、直到 release() 被调用才会 resolve
+* 的 Promise，从而把锁"长期持有"而不是只在回调执行期间持有。
+*/
+async function tryAcquireTabLock(lockName) {
+	if (typeof navigator === "undefined" || !navigator.locks) return () => {};
+	let release;
+	if (!await new Promise((resolveAcquired) => {
+		navigator.locks.request(lockName, { ifAvailable: true }, (lock) => {
+			if (!lock) {
+				resolveAcquired(false);
+				return;
+			}
+			resolveAcquired(true);
+			return new Promise((resolveRelease) => {
+				release = resolveRelease;
+			});
+		});
+	})) return null;
+	return () => release?.();
+}
+/**
+* Web (sqlite-wasm) 适配器。每次调用 createWebAdapter() 返回一个状态独立的新实例——
+* promiser/dbId 保存在这个函数的闭包里，不是模块级单例，允许同一进程里存在多个互不干扰的
+* 实例（例如测试）。
+*/
+function createWebAdapter(options = {}) {
+	const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const fallbackToMemory = options.fallbackToMemory ?? true;
+	const singleTabLock = options.singleTabLock ?? true;
+	let promiser = null;
+	let currentDbId;
+	let releaseTabLock = null;
+	const client = {
+		async select(sql, params = []) {
+			if (!promiser || currentDbId === void 0) throw new DbError("[Web DB] Database not initialized. Call initialize() first.");
+			const response = await promiser("exec", {
+				dbId: currentDbId,
+				sql,
+				bind: params,
+				resultRows: [],
+				rowMode: "object"
+			});
+			if (response.type === "error") throw new DbExecutionError(sql, params, new Error(response.result.message));
+			return response.result.resultRows || [];
+		},
+		async execute(sql, params = []) {
+			if (!promiser || currentDbId === void 0) throw new DbError("[Web DB] Database not initialized. Call initialize() first.");
+			const response = await promiser("exec", {
+				dbId: currentDbId,
+				sql,
+				bind: params,
+				countChanges: true,
+				lastInsertRowId: true
+			});
+			if (response.type === "error") throw new DbExecutionError(sql, params, new Error(response.result.message));
+			return {
+				lastInsertId: response.result.lastInsertRowId !== void 0 ? Number(response.result.lastInsertRowId) : void 0,
+				rowsAffected: response.result.changeCount ?? 0
+			};
+		},
+		async close() {
+			if (promiser && currentDbId !== void 0) try {
+				const closeResponse = await promiser("close", { dbId: currentDbId });
+				if (closeResponse.type === "error") throw new DbCloseError(new Error(closeResponse.result.message));
+			} finally {
+				promiser = null;
+				currentDbId = void 0;
+				releaseTabLock?.();
+				releaseTabLock = null;
+			}
+		}
+	};
+	return {
+		singleConnection: true,
+		async initialize(config) {
+			if (promiser) return client;
+			const isOpfsSupported = typeof navigator !== "undefined" && typeof navigator.storage !== "undefined" && !!navigator.storage.getDirectory;
+			const isCrossOriginIsolated = typeof window !== "undefined" && window.crossOriginIsolated;
+			let filename = ":memory:";
+			if (!isOpfsSupported || !isCrossOriginIsolated) {
+				if (!fallbackToMemory) throw new DbInitializationError(/* @__PURE__ */ new Error("[Web DB] OPFS is not available (unsupported or not cross-origin isolated) and fallbackToMemory is false."));
+				console.warn("[Web DB] OPFS is not fully supported or cross-origin isolated. Falling back to in-memory mode.");
+			} else try {
+				const root = await navigator.storage.getDirectory();
+				await root.getFileHandle("test_opfs_support", { create: true });
+				await root.removeEntry("test_opfs_support").catch(() => {});
+				filename = `file:${config.name}.db?vfs=opfs`;
+			} catch (opfsError) {
+				if (!fallbackToMemory) throw new DbInitializationError(new Error("[Web DB] OPFS initialization failed and fallbackToMemory is false.", { cause: opfsError }));
+				console.warn("[Web DB] OPFS initialization failed or file access denied. Falling back to in-memory mode.", opfsError);
+				filename = ":memory:";
+			}
+			if (filename !== ":memory:" && singleTabLock) {
+				const release = await tryAcquireTabLock(`cross-sqlite-client:${config.name}`);
+				if (!release) throw new DbTabLockError();
+				releaseTabLock = release;
+			}
+			try {
+				const readyPromise = sqlite3Worker1Promiser({ onerror: (...args) => console.error("[Web DB] sqlite3Worker1Promiser error:", ...args) });
+				let timeoutId;
+				const timeoutPromise = new Promise((_, reject) => {
+					timeoutId = setTimeout(() => reject(/* @__PURE__ */ new Error(`[Web DB] Timed out after ${timeoutMs}ms waiting for the SQLite worker to become ready (it may have failed to load).`)), timeoutMs);
+				});
+				try {
+					promiser = await Promise.race([readyPromise, timeoutPromise]);
+				} finally {
+					clearTimeout(timeoutId);
+				}
+				const openResponse = await promiser("open", { filename });
+				if (openResponse.type === "error") throw new DbInitializationError(/* @__PURE__ */ new Error(`Failed to open database: ${openResponse.result.message}`));
+				currentDbId = openResponse.dbId;
+				if (currentDbId === void 0) throw new DbInitializationError(/* @__PURE__ */ new Error("Database opened successfully but dbId is undefined. This indicates an unexpected library behavior."));
+				return client;
+			} catch (error) {
+				promiser = null;
+				currentDbId = void 0;
+				releaseTabLock?.();
+				releaseTabLock = null;
+				throw error instanceof DbInitializationError ? error : new DbInitializationError(error);
+			}
+		}
+	};
+}
+/**
+* 自定义事务型 executor，仅用于单连接适配器（web / memory）。
+*
+* 为什么不能给 Tauri 用：@tauri-apps/plugin-sql 底层是 sqlx::Pool<Sqlite> 连接池，每次
+* execute() 调用独立获取/归还连接，不保证 BEGIN 和 COMMIT 落在同一条物理连接上，事务可能被
+* 悄悄拆散且不报错。createDbClient 会在 adapter.singleConnection !== true 时拒绝非默认
+* executor，但直接调用 runMigrations() 时不会有这层保护，调用方需自行确保只在单连接适配器上使用。
+*/
+const runTransactionalMigration = async (db, migration, recordVersion) => {
+	await db.execute("BEGIN;");
+	try {
+		for (const statement of migration.statements) await db.execute(statement);
+		await recordVersion();
+		await db.execute("COMMIT;");
+	} catch (e) {
+		await db.execute("ROLLBACK;").catch(() => {});
+		throw e;
+	}
+};
+const transactionalExecutor = Object.assign(runTransactionalMigration, { requiresSingleConnection: true });
+//#endregion
+export { createWebAdapter, transactionalExecutor, tryAcquireTabLock };

package/dist/core/index.d.ts

@@ -0,0 +1,50 @@
+import { a as Migration, i as DbClient, n as DbAdapter, o as MigrationExecutor, r as DbAdapterConfig, s as MigrationOptions, t as CreateDbClientOptions } from "../types-XKvAFU82.js";
+//#region src/core/migrate.d.ts
+export declare const defaultExecutor: MigrationExecutor;
+/**
+ * 按 version 顺序执行尚未应用的迁移。每条语句独立执行，没有事务包裹；若某条迁移执行到
+ * 一半失败，下次启动会从同一个 version 重新开始，重新跑一遍这个 version 里的全部语句。
+ *
+ * 不能简单地在多次 execute() 调用之间手动包一层 BEGIN/COMMIT/ROLLBACK 来补救：部分适配器
+ * （例如 Tauri 端的 @tauri-apps/plugin-sql）底层是连接池，每次 execute() 调用都独立获取/
+ * 归还一个物理连接，不保证 BEGIN 和 COMMIT 落在同一条连接上，事务可能被悄悄拆散而不报错。
+ * 只有 adapter.singleConnection === true 的适配器才能安全地使用自定义的事务型 executor
+ * （见 adapters/web.ts 的 transactionalExecutor，以及 createDbClient 里的运行时检查）。
+ *
+ * 因此，MIGRATIONS 里的每条语句都必须自身是可安全重试的：
+ * - 建表/建索引一律用 CREATE TABLE/INDEX IF NOT EXISTS；
+ * - 以后如果要写重命名列、迁移数据这类不可重复执行的语句，先查询当前 schema 状态判断
+ *   这一步是否已经做过（例如 `SELECT 1 FROM pragma_table_info('t') WHERE name = '...'`），
+ *   已完成就跳过，而不是依赖事务回滚。
+ */
+export declare function runMigrations(db: Pick<DbClient, "execute" | "select">, migrations: Migration[], options?: MigrationOptions): Promise<void>;
+//#endregion
+//#region src/core/errors.d.ts
+export declare class DbError extends Error {
+  cause?: unknown;
+  constructor(message: string, cause?: unknown);
+}
+export declare class DbInitializationError extends DbError {
+  constructor(cause?: unknown);
+}
+export declare class DbExecutionError extends DbError {
+  sql: string;
+  params: unknown[];
+  constructor(sql: string, params: unknown[], cause?: unknown);
+}
+export declare class DbCloseError extends DbError {
+  constructor(cause?: unknown);
+}
+/**
+ * 另一个浏览器标签页/窗口已经持有同一个 OPFS 数据库文件的跨标签页锁。
+ * 只有 web 适配器在 singleTabLock 启用时会抛出这个类型；调用方可以据此展示
+ * "请关闭其他标签页" 之类的提示，而不是把它当成普通的初始化失败处理。
+ */
+export declare class DbTabLockError extends DbError {
+  constructor(cause?: unknown);
+}
+//#endregion
+//#region src/core/index.d.ts
+export declare function createDbClient(options: CreateDbClientOptions): Promise<DbClient>;
+//#endregion
+export type { CreateDbClientOptions, DbAdapter, DbAdapterConfig, DbClient, Migration, MigrationExecutor, MigrationOptions };

package/dist/core/index.js

@@ -0,0 +1,47 @@
+import { a as DbTabLockError, i as DbInitializationError, n as DbError, r as DbExecutionError, t as DbCloseError } from "../errors-D9KnLHTp.js";
+//#region src/core/migrate.ts
+const defaultExecutor = async (db, migration, recordVersion) => {
+	for (const statement of migration.statements) await db.execute(statement);
+	await recordVersion();
+};
+/**
+* 按 version 顺序执行尚未应用的迁移。每条语句独立执行，没有事务包裹；若某条迁移执行到
+* 一半失败，下次启动会从同一个 version 重新开始，重新跑一遍这个 version 里的全部语句。
+*
+* 不能简单地在多次 execute() 调用之间手动包一层 BEGIN/COMMIT/ROLLBACK 来补救：部分适配器
+* （例如 Tauri 端的 @tauri-apps/plugin-sql）底层是连接池，每次 execute() 调用都独立获取/
+* 归还一个物理连接，不保证 BEGIN 和 COMMIT 落在同一条连接上，事务可能被悄悄拆散而不报错。
+* 只有 adapter.singleConnection === true 的适配器才能安全地使用自定义的事务型 executor
+* （见 adapters/web.ts 的 transactionalExecutor，以及 createDbClient 里的运行时检查）。
+*
+* 因此，MIGRATIONS 里的每条语句都必须自身是可安全重试的：
+* - 建表/建索引一律用 CREATE TABLE/INDEX IF NOT EXISTS；
+* - 以后如果要写重命名列、迁移数据这类不可重复执行的语句，先查询当前 schema 状态判断
+*   这一步是否已经做过（例如 `SELECT 1 FROM pragma_table_info('t') WHERE name = '...'`），
+*   已完成就跳过，而不是依赖事务回滚。
+*/
+async function runMigrations(db, migrations, options) {
+	const tableName = options?.tableName ?? "schema_version";
+	const executor = options?.executor ?? defaultExecutor;
+	for (const migration of migrations) if (migration.version <= 0) throw new Error(`Migration version must be >= 1, got ${migration.version}.`);
+	await db.execute(`CREATE TABLE IF NOT EXISTS ${tableName} (
+      version INTEGER PRIMARY KEY,
+      applied_at INTEGER NOT NULL DEFAULT (cast(strftime('%s', 'subsec') * 1000 as int))
+    );`);
+	const currentVersion = (await db.select(`SELECT MAX(version) as version FROM ${tableName};`))[0]?.version ?? 0;
+	const pending = migrations.filter((migration) => migration.version > currentVersion).sort((a, b) => a.version - b.version);
+	for (const migration of pending) await executor(db, migration, async () => {
+		await db.execute(`INSERT INTO ${tableName} (version) VALUES (?);`, [migration.version]);
+	});
+}
+//#endregion
+//#region src/core/index.ts
+async function createDbClient(options) {
+	const { adapter } = options;
+	if ((options.migrationOptions?.executor)?.requiresSingleConnection && !adapter.singleConnection) throw new Error("This MigrationExecutor requires a single-connection adapter (adapter.singleConnection !== true); a custom executor that manually manages BEGIN/COMMIT is not safe here. Use the default executor or an adapter with singleConnection: true.");
+	const client = await adapter.initialize({ name: options.name });
+	if (options.migrations?.length) await runMigrations(client, options.migrations, options.migrationOptions);
+	return client;
+}
+//#endregion
+export { DbCloseError, DbError, DbExecutionError, DbInitializationError, DbTabLockError, createDbClient, defaultExecutor, runMigrations };

package/dist/errors-D9KnLHTp.js

@@ -0,0 +1,44 @@
+//#region src/core/errors.ts
+var DbError = class extends Error {
+	cause;
+	constructor(message, cause) {
+		super(message);
+		this.cause = cause;
+		this.name = "DbError";
+	}
+};
+var DbInitializationError = class extends DbError {
+	constructor(cause) {
+		super("Failed to initialize database", cause);
+		this.name = "DbInitializationError";
+	}
+};
+var DbExecutionError = class extends DbError {
+	sql;
+	params;
+	constructor(sql, params, cause) {
+		super(`SQL execution failed: ${sql}`, cause);
+		this.sql = sql;
+		this.params = params;
+		this.name = "DbExecutionError";
+	}
+};
+var DbCloseError = class extends DbError {
+	constructor(cause) {
+		super("Failed to close database", cause);
+		this.name = "DbCloseError";
+	}
+};
+/**
+* 另一个浏览器标签页/窗口已经持有同一个 OPFS 数据库文件的跨标签页锁。
+* 只有 web 适配器在 singleTabLock 启用时会抛出这个类型；调用方可以据此展示
+* "请关闭其他标签页" 之类的提示，而不是把它当成普通的初始化失败处理。
+*/
+var DbTabLockError = class extends DbError {
+	constructor(cause) {
+		super("Another browser tab/window already has this database open", cause);
+		this.name = "DbTabLockError";
+	}
+};
+//#endregion
+export { DbTabLockError as a, DbInitializationError as i, DbError as n, DbExecutionError as r, DbCloseError as t };

package/dist/react/index.d.ts

@@ -0,0 +1,34 @@
+import { i as DbClient } from "../types-XKvAFU82.js";
+import React from "react";
+//#region src/react/DatabaseProvider.d.ts
+interface DatabaseContextType {
+  dbClient: DbClient | null;
+  isDbReady: boolean;
+  isLoading: boolean;
+  dbError: Error | null;
+}
+interface DatabaseProviderProps {
+  /**
+   * 由调用方负责创建（通常是 createDbClient(...) 的返回值）。DatabaseProvider 不再自己
+   * 决定用哪个 adapter/迁移哪些 migrations——那是应用层的职责，见 README 里的 appDb 示例。
+   *
+   * 没有 retry：这个 Promise 只会 settle 一次，重试的语义交给调用方——想重试就在自己的状态
+   * 里创建一个新的 client Promise，再把新引用传给这个 prop，effect 依赖 [client] 会自动
+   * 重新走一遍下面的初始化逻辑。
+   *
+   * DatabaseProvider 不拥有 client 的生命周期，卸载时也不会调用 client.close()：谁创建
+   * 的 client 谁负责关闭。如果 close() 交给这里，而调用方（比如应用级单例的
+   * getAppDbClient()）又缓存/复用同一个 client Promise，Provider 一旦被卸载再重新挂载
+   * （条件渲染、测试环境、会重新 mount 的路由/key 边界……），第二次挂载就会解析到同一个
+   * 已经被 close 过的 client——isDbReady 变成 true 但连接其实是死的。需要跟随组件生命周期
+   * 关闭连接的调用方，应该在自己创建 client 的地方管理 close()，而不是依赖这里。
+   */
+  client: DbClient | Promise<DbClient>;
+  children: React.ReactNode;
+}
+export declare const DatabaseProvider: React.FC<DatabaseProviderProps>;
+//#endregion
+//#region src/react/useDatabase.d.ts
+export declare const useDatabase: () => DatabaseContextType;
+//#endregion
+export type { DatabaseContextType, DatabaseProviderProps };

package/dist/react/index.js

@@ -0,0 +1,47 @@
+import { createContext, useContext, useEffect, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/react/DatabaseProvider.tsx
+const DatabaseContext = createContext(void 0);
+const DatabaseProvider = ({ client, children }) => {
+	const [dbClient, setDbClient] = useState(null);
+	const [isDbReady, setIsDbReady] = useState(false);
+	const [isLoading, setIsLoading] = useState(true);
+	const [dbError, setDbError] = useState(null);
+	useEffect(() => {
+		let cancelled = false;
+		setIsLoading(true);
+		setDbError(null);
+		Promise.resolve(client).then((resolvedClient) => {
+			if (cancelled) return;
+			setDbClient(resolvedClient);
+			setIsDbReady(true);
+		}).catch((error) => {
+			if (cancelled) return;
+			setDbError(error instanceof Error ? error : new Error(String(error)));
+		}).finally(() => {
+			if (!cancelled) setIsLoading(false);
+		});
+		return () => {
+			cancelled = true;
+		};
+	}, [client]);
+	const value = {
+		dbClient,
+		isDbReady,
+		isLoading,
+		dbError
+	};
+	return /* @__PURE__ */ jsx(DatabaseContext.Provider, {
+		value,
+		children
+	});
+};
+//#endregion
+//#region src/react/useDatabase.ts
+const useDatabase = () => {
+	const context = useContext(DatabaseContext);
+	if (context === void 0) throw new Error("useDatabase must be used within a DatabaseProvider");
+	return context;
+};
+//#endregion
+export { DatabaseProvider, useDatabase };

package/dist/types-XKvAFU82.d.ts

@@ -0,0 +1,45 @@
+//#region src/core/types.d.ts
+interface DbClient {
+  select<T>(sql: string, params?: unknown[]): Promise<T[]>;
+  execute(sql: string, params?: unknown[]): Promise<{
+    lastInsertId?: number;
+    rowsAffected?: number;
+  }>;
+  close(): Promise<void>;
+}
+interface DbAdapterConfig {
+  /** 数据库文件名/标识，如 "my-app"（不含扩展名） */
+  name: string;
+}
+interface DbAdapter {
+  initialize(config: DbAdapterConfig): Promise<DbClient>;
+  /**
+   * 该适配器的每次 execute()/select() 调用是否保证落在同一条物理连接上。
+   * web/memory 适配器是单一持久连接，为 true；Tauri 适配器底层是
+   * sqlx::Pool<Sqlite> 连接池，不同调用可能拿到不同物理连接，为 false。
+   * 决定了自定义 MigrationExecutor 里手写的 BEGIN/COMMIT 是否安全。
+   */
+  singleConnection: boolean;
+}
+interface Migration {
+  version: number;
+  statements: string[];
+}
+type MigrationExecutor = (db: Pick<DbClient, "execute" | "select">, migration: Migration,
+/** 记录 schema_version 的回调；executor 决定何时调用（比如放进自己的事务里） */
+recordVersion: () => Promise<void>) => Promise<void>;
+interface MigrationOptions {
+  /** schema 版本表名，默认 "schema_version" */
+  tableName?: string;
+  /** 自定义事务包裹策略；仅能用于 adapter.singleConnection === true 的适配器 */
+  executor?: MigrationExecutor;
+}
+interface CreateDbClientOptions {
+  name: string;
+  /** 必须显式传入实例，库不提供 'auto'/'web'/'tauri' 字符串快捷方式 */
+  adapter: DbAdapter;
+  migrations?: Migration[];
+  migrationOptions?: MigrationOptions;
+}
+//#endregion
+export { Migration as a, DbClient as i, DbAdapter as n, MigrationExecutor as o, DbAdapterConfig as r, MigrationOptions as s, CreateDbClientOptions as t };

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "cross-sqlite-client",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Cross-platform (Web + Tauri) SQLite client with a shared migration framework and React bindings.",
+  "license": "MIT",
+  "author": "ueaner",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ueaner/cross-sqlite-client.git"
+  },
+  "homepage": "https://github.com/ueaner/cross-sqlite-client#readme",
+  "bugs": {
+    "url": "https://github.com/ueaner/cross-sqlite-client/issues"
+  },
+  "keywords": [
+    "sqlite",
+    "tauri",
+    "sqlite-wasm",
+    "opfs",
+    "migration",
+    "react"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js"
+    },
+    "./adapters/web": {
+      "types": "./dist/adapters/web.d.ts",
+      "import": "./dist/adapters/web.js"
+    },
+    "./adapters/tauri": {
+      "types": "./dist/adapters/tauri.d.ts",
+      "import": "./dist/adapters/tauri.js"
+    },
+    "./adapters/memory": {
+      "types": "./dist/adapters/memory.d.ts",
+      "import": "./dist/adapters/memory.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run",
+    "lint": "oxlint src test"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "optionalDependencies": {
+    "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
+    "@tauri-apps/plugin-sql": "^2.4.1"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.18",
+    "react": "^19.2.8",
+    "tsdown": "^0.23.0",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.0"
+  }
+}