cross-sqlite-client 0.1.0 → 0.2.0

package/dist/adapters/web.js

@@ -1,10 +1,21 @@
-import { a as DbTabLockError, i as DbInitializationError, n as DbError, r as DbExecutionError, t as DbCloseError } from "../errors-D9KnLHTp.js";
+import { i as DbInitializationError, n as DbError, o as DbTabLockError, r as DbExecutionError, t as DbCloseError } from "../errors-DwJZz1Jx.js";
 import { sqlite3Worker1Promiser } from "@sqlite.org/sqlite-wasm";
 //#region src/adapters/web.ts
 const DEFAULT_TIMEOUT_MS = 15e3;
 /**
+* promiser 的错误以 reject 形式出现，且 rejection 值是 {type:"error", result:{message,...}}
+* 形状的普通对象而不是 Error 实例（见 src/types/sqlite-wasm.d.ts 里 Promiser 的说明）。
+*/
+function isPromiserError(error) {
+	return typeof error === "object" && error !== null && error.type === "error" && typeof error.result?.message === "string";
+}
+/** 从 promiser 的 rejection 值里提取可读消息；不是 promiser 错误就原样返回 */
+function promiserErrorCause(error) {
+	return isPromiserError(error) ? new Error(error.result.message) : error;
+}
+/**
 * 用 Web Locks API 尝试（不等待）拿到一个跨标签页命名锁。拿不到（另一个标签页已持有）时
-* resolve 到 null；拿到时返回一个 release() 函数，调用方后续必须调用它来释放锁。
+* 返回 null；拿到时返回一个 release() 函数，调用方后续必须调用它来释放锁。
 *
 * 实现上依赖一个常见技巧：navigator.locks.request() 的回调函数返回什么 Promise，锁就持有到
 * 那个 Promise settle 为止；这里让回调返回一个我们自己创建、直到 release() 被调用才会 resolve
@@ -36,97 +47,175 @@ function createWebAdapter(options = {}) {
 	const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
 	const fallbackToMemory = options.fallbackToMemory ?? true;
 	const singleTabLock = options.singleTabLock ?? true;
+	const logger = options.logger ?? console;
 	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,
+	let worker = null;
+	let initPromise = null;
+	function requirePromiser() {
+		if (!promiser || currentDbId === void 0) throw new DbError("[Web DB] Database not initialized. Call initialize() first.");
+		return {
+			p: promiser,
+			dbId: currentDbId
+		};
+	}
+	async function exec(sql, params) {
+		const { p, dbId } = requirePromiser();
+		try {
+			return await p("exec", {
+				dbId,
 				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,
+				rowMode: "object",
 				countChanges: true,
 				lastInsertRowId: true
 			});
-			if (response.type === "error") throw new DbExecutionError(sql, params, new Error(response.result.message));
+		} catch (error) {
+			throw new DbExecutionError(sql, params, promiserErrorCause(error));
+		}
+	}
+	const client = {
+		async select(sql, params = []) {
+			return (await exec(sql, params)).result.resultRows || [];
+		},
+		async execute(sql, params = []) {
+			const response = await exec(sql, params);
 			return {
 				lastInsertId: response.result.lastInsertRowId !== void 0 ? Number(response.result.lastInsertRowId) : void 0,
 				rowsAffected: response.result.changeCount ?? 0
 			};
 		},
+		async executeBatch(statements) {
+			if (statements.length === 0) return;
+			if (statements.every((s) => typeof s === "string" || s.params === void 0 || s.params.length === 0)) {
+				const { p, dbId } = requirePromiser();
+				const sql = statements.map((s) => typeof s === "string" ? s : s.sql).join("\n;\n");
+				try {
+					await p("exec", {
+						dbId,
+						sql
+					});
+				} catch (error) {
+					throw new DbExecutionError(sql, [], promiserErrorCause(error));
+				}
+				return;
+			}
+			for (const statement of statements) {
+				const sql = typeof statement === "string" ? statement : statement.sql;
+				const params = typeof statement === "string" ? [] : statement.params ?? [];
+				await client.execute(sql, params);
+			}
+		},
 		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));
+			const pending = initPromise;
+			initPromise = null;
+			if (pending) await pending.catch(() => {});
+			const p = promiser;
+			const dbId = currentDbId;
+			const w = worker;
+			promiser = null;
+			currentDbId = void 0;
+			worker = null;
+			releaseTabLock?.();
+			releaseTabLock = null;
+			try {
+				if (p && dbId !== void 0) await p("close", { dbId });
+			} catch (error) {
+				throw new DbCloseError(promiserErrorCause(error));
 			} finally {
-				promiser = null;
-				currentDbId = void 0;
-				releaseTabLock?.();
-				releaseTabLock = null;
+				w?.terminate();
 			}
 		}
 	};
-	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:";
+	function createWorker() {
+		try {
+			const factory = sqlite3Worker1Promiser.defaultConfig?.worker;
+			if (typeof factory === "function") return factory();
+			return factory;
+		} catch {
+			return;
+		}
+	}
+	async function openDatabase(p, filename) {
+		const openResponse = await p("open", { filename });
+		if (openResponse.dbId === void 0) throw new DbInitializationError(/* @__PURE__ */ new Error("Database opened successfully but dbId is undefined. This indicates an unexpected library behavior."));
+		return openResponse.dbId;
+	}
+	async function doInitialize(config) {
+		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."));
+			logger.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 }));
+			logger.warn("[Web DB] OPFS initialization failed or file access denied. Falling back to in-memory mode.", opfsError);
+			filename = ":memory:";
+		}
+		if (filename !== ":memory:" && singleTabLock) {
+			let release;
+			try {
+				release = await tryAcquireTabLock(`cross-sqlite-client:${config.name}`);
+			} catch (error) {
+				throw new DbInitializationError(error);
 			}
-			if (filename !== ":memory:" && singleTabLock) {
-				const release = await tryAcquireTabLock(`cross-sqlite-client:${config.name}`);
-				if (!release) throw new DbTabLockError();
-				releaseTabLock = release;
+			if (!release) throw new DbTabLockError();
+			releaseTabLock = release;
+		}
+		try {
+			worker = createWorker() ?? null;
+			const readyPromise = sqlite3Worker1Promiser({
+				worker: worker ?? void 0,
+				onerror: (...args) => logger.error("[Web DB] sqlite3Worker1Promiser error:", ...args)
+			});
+			let rejectTimeout;
+			const timeoutPromise = new Promise((_, reject) => {
+				rejectTimeout = reject;
+			});
+			const timeoutId = setTimeout(() => rejectTimeout(/* @__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);
 			}
 			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);
+				currentDbId = await openDatabase(promiser, filename);
+			} catch (openError) {
+				if (filename !== ":memory:" && fallbackToMemory) {
+					logger.warn("[Web DB] Failed to open the OPFS database. Falling back to in-memory mode.", promiserErrorCause(openError));
+					currentDbId = await openDatabase(promiser, ":memory:");
+				} else throw openError;
+			}
+			return client;
+		} catch (error) {
+			promiser = null;
+			currentDbId = void 0;
+			worker?.terminate();
+			worker = null;
+			releaseTabLock?.();
+			releaseTabLock = null;
+			if (error instanceof DbInitializationError) throw error;
+			throw new DbInitializationError(promiserErrorCause(error));
+		}
+	}
+	return {
+		singleConnection: true,
+		initialize(config) {
+			if (!initPromise) {
+				initPromise = doInitialize(config);
+				initPromise.catch(() => {
+					initPromise = null;
 				});
-				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);
 			}
+			return initPromise;
 		}
 	};
 }
@@ -135,13 +224,13 @@ function createWebAdapter(options = {}) {
 *
 * 为什么不能给 Tauri 用：@tauri-apps/plugin-sql 底层是 sqlx::Pool<Sqlite> 连接池，每次
 * execute() 调用独立获取/归还连接，不保证 BEGIN 和 COMMIT 落在同一条物理连接上，事务可能被
-* 悄悄拆散且不报错。createDbClient 会在 adapter.singleConnection !== true 时拒绝非默认
-* executor，但直接调用 runMigrations() 时不会有这层保护，调用方需自行确保只在单连接适配器上使用。
+* 悄悄拆散且不报错。createDbClient 靠 executor 上的 requiresSingleConnection 标记拒绝这种
+* 组合，但直接调用 runMigrations() 时不会有这层保护，调用方需自行确保只在单连接适配器上使用。
 */
 const runTransactionalMigration = async (db, migration, recordVersion) => {
 	await db.execute("BEGIN;");
 	try {
-		for (const statement of migration.statements) await db.execute(statement);
+		await db.executeBatch(migration.statements);
 		await recordVersion();
 		await db.execute("COMMIT;");
 	} catch (e) {

package/dist/core/index.d.ts

@@ -1,8 +1,8 @@
-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";
+import { a as DbClient, c as MigrationExecutor, i as DbAdapterConfig, l as MigrationOptions, n as CreateDbClientOptions, o as Logger, r as DbAdapter, s as Migration, t as BatchStatement } from "../types-Dm9OqT6i.js";
 //#region src/core/migrate.d.ts
 export declare const defaultExecutor: MigrationExecutor;
 /**
- * 按 version 顺序执行尚未应用的迁移。每条语句独立执行，没有事务包裹；若某条迁移执行到
+ * 按 version 顺序执行尚未应用的迁移。默认每条语句独立执行，没有事务包裹；若某条迁移执行到
  * 一半失败，下次启动会从同一个 version 重新开始，重新跑一遍这个 version 里的全部语句。
  *
  * 不能简单地在多次 execute() 调用之间手动包一层 BEGIN/COMMIT/ROLLBACK 来补救：部分适配器
@@ -16,8 +16,14 @@ export declare const defaultExecutor: MigrationExecutor;
  * - 以后如果要写重命名列、迁移数据这类不可重复执行的语句，先查询当前 schema 状态判断
  *   这一步是否已经做过（例如 `SELECT 1 FROM pragma_table_info('t') WHERE name = '...'`），
  *   已完成就跳过，而不是依赖事务回滚。
+ *
+ * executor 抛出的错误会被包装成 DbMigrationError（携带失败的 version）再向上抛。
+ *
+ * 不可重入：同一个数据库同一时间只允许一个 runMigrations 在执行。并发调用会各自读取
+ * 相同起点并重复执行——语句幂等所以无害，但两边都会写版本记录，后到一方撞主键约束，
+ * 报出"迁移失败"的误导性错误。
  */
-export declare function runMigrations(db: Pick<DbClient, "execute" | "select">, migrations: Migration[], options?: MigrationOptions): Promise<void>;
+export declare function runMigrations(db: Pick<DbClient, "execute" | "select" | "executeBatch">, migrations: Migration[], options?: MigrationOptions): Promise<void>;
 //#endregion
 //#region src/core/errors.d.ts
 export declare class DbError extends Error {
@@ -32,6 +38,15 @@ export declare class DbExecutionError extends DbError {
   params: unknown[];
   constructor(sql: string, params: unknown[], cause?: unknown);
 }
+/**
+ * 某条迁移执行失败。version 指出失败的是哪个迁移版本，cause 是底层原始错误
+ * （通常是 DbExecutionError）。runMigrations 会把 executor 抛出的非 DbMigrationError
+ * 错误统一包装成这个类型再向上抛。
+ */
+export declare class DbMigrationError extends DbError {
+  version: number;
+  constructor(version: number, cause?: unknown);
+}
 export declare class DbCloseError extends DbError {
   constructor(cause?: unknown);
 }
@@ -47,4 +62,4 @@ export declare class DbTabLockError extends DbError {
 //#region src/core/index.d.ts
 export declare function createDbClient(options: CreateDbClientOptions): Promise<DbClient>;
 //#endregion
-export type { CreateDbClientOptions, DbAdapter, DbAdapterConfig, DbClient, Migration, MigrationExecutor, MigrationOptions };
+export type { BatchStatement, CreateDbClientOptions, DbAdapter, DbAdapterConfig, DbClient, Logger, Migration, MigrationExecutor, MigrationOptions };

package/dist/core/index.js

@@ -1,11 +1,16 @@
-import { a as DbTabLockError, i as DbInitializationError, n as DbError, r as DbExecutionError, t as DbCloseError } from "../errors-D9KnLHTp.js";
+import { a as DbMigrationError, i as DbInitializationError, n as DbError, o as DbTabLockError, r as DbExecutionError, t as DbCloseError } from "../errors-DwJZz1Jx.js";
 //#region src/core/migrate.ts
+/** 表名/PRAGMA 名等要拼进 SQL 的标识符，只允许这个白名单，杜绝注入 */
+const IDENTIFIER_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function assertIdentifier(value, what) {
+	if (!IDENTIFIER_RE.test(value)) throw new Error(`${what} must match ${IDENTIFIER_RE} (letters, digits, underscore; not starting with a digit), got ${JSON.stringify(value)}.`);
+}
 const defaultExecutor = async (db, migration, recordVersion) => {
-	for (const statement of migration.statements) await db.execute(statement);
+	await db.executeBatch(migration.statements);
 	await recordVersion();
 };
 /**
-* 按 version 顺序执行尚未应用的迁移。每条语句独立执行，没有事务包裹；若某条迁移执行到
+* 按 version 顺序执行尚未应用的迁移。默认每条语句独立执行，没有事务包裹；若某条迁移执行到
 * 一半失败，下次启动会从同一个 version 重新开始，重新跑一遍这个 version 里的全部语句。
 *
 * 不能简单地在多次 execute() 调用之间手动包一层 BEGIN/COMMIT/ROLLBACK 来补救：部分适配器
@@ -19,29 +24,82 @@ const defaultExecutor = async (db, migration, recordVersion) => {
 * - 以后如果要写重命名列、迁移数据这类不可重复执行的语句，先查询当前 schema 状态判断
 *   这一步是否已经做过（例如 `SELECT 1 FROM pragma_table_info('t') WHERE name = '...'`），
 *   已完成就跳过，而不是依赖事务回滚。
+*
+* executor 抛出的错误会被包装成 DbMigrationError（携带失败的 version）再向上抛。
+*
+* 不可重入：同一个数据库同一时间只允许一个 runMigrations 在执行。并发调用会各自读取
+* 相同起点并重复执行——语句幂等所以无害，但两边都会写版本记录，后到一方撞主键约束，
+* 报出"迁移失败"的误导性错误。
 */
 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}.`);
+	const logger = options?.logger ?? console;
+	assertIdentifier(tableName, "Migration tableName");
+	const seen = /* @__PURE__ */ new Set();
+	for (const migration of migrations) {
+		if (!Number.isInteger(migration.version) || migration.version <= 0) throw new Error(`Migration version must be a positive integer, got ${migration.version}.`);
+		if (seen.has(migration.version)) throw new Error(`Duplicate migration version ${migration.version}.`);
+		seen.add(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))
+      applied_at INTEGER NOT NULL DEFAULT 0
     );`);
-	const currentVersion = (await db.select(`SELECT MAX(version) as version FROM ${tableName};`))[0]?.version ?? 0;
+	const rows = await db.select(`SELECT version FROM ${tableName};`);
+	const applied = new Set(rows.map((row) => row.version));
+	const currentVersion = Math.max(0, ...applied);
+	const maxProvided = migrations.reduce((max, migration) => Math.max(max, migration.version), 0);
+	if (currentVersion > maxProvided) logger.warn(`[Migrations] Database schema version (${currentVersion}) is newer than the highest migration provided by this app (${maxProvided}). The database was likely created by a newer app version; no migrations were run.`);
+	const holes = migrations.filter((migration) => migration.version < currentVersion && !applied.has(migration.version));
+	if (holes.length > 0) logger.warn(`[Migrations] ${holes.length} migration(s) with version below the current schema version (${currentVersion}) were never applied and are being skipped: ${holes.map((migration) => migration.version).join(", ")}. If these are hotfix migrations for an older release line, apply them deliberately (e.g. with a dedicated executor) instead of relying on the default runner.`);
 	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]);
-	});
+	for (const migration of pending) try {
+		await executor(db, migration, async () => {
+			await db.execute(`INSERT INTO ${tableName} (version, applied_at) VALUES (?, ?);`, [migration.version, Date.now()]);
+		});
+	} catch (error) {
+		throw error instanceof DbMigrationError ? error : new DbMigrationError(migration.version, error);
+	}
 }
 //#endregion
 //#region src/core/index.ts
+/** PRAGMA 的字符串值只允许枚举式 token（WAL、NORMAL……），杜绝拼 SQL 注入 */
+const PRAGMA_VALUE_RE = /^[A-Za-z0-9_]+$/;
+async function applyPragmas(client, pragmas) {
+	for (const [key, rawValue] of Object.entries(pragmas)) {
+		assertIdentifier(key, "PRAGMA name");
+		let value;
+		if (typeof rawValue === "boolean") value = rawValue ? "1" : "0";
+		else if (typeof rawValue === "number") {
+			if (!Number.isFinite(rawValue)) throw new Error(`PRAGMA ${key}: number values must be finite, got ${rawValue}.`);
+			value = String(rawValue);
+		} else {
+			if (!PRAGMA_VALUE_RE.test(rawValue)) throw new Error(`PRAGMA ${key}: string values must match ${PRAGMA_VALUE_RE}, got ${JSON.stringify(rawValue)}.`);
+			value = rawValue;
+		}
+		await client.execute(`PRAGMA ${key} = ${value};`);
+	}
+}
 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.");
+	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 logger = options.logger ?? console;
 	const client = await adapter.initialize({ name: options.name });
-	if (options.migrations?.length) await runMigrations(client, options.migrations, options.migrationOptions);
+	try {
+		if (options.pragmas) {
+			if (!adapter.singleConnection) logger.warn("[PRAGMA] This adapter uses a connection pool; connection-level pragmas (e.g. foreign_keys, busy_timeout) apply only to one pooled connection and will silently not hold for later queries. Database-level pragmas (e.g. journal_mode, user_version) are unaffected.");
+			await applyPragmas(client, options.pragmas);
+		}
+		if (options.migrations) await runMigrations(client, options.migrations, {
+			...options.migrationOptions,
+			logger: options.migrationOptions?.logger ?? logger
+		});
+	} catch (error) {
+		await client.close().catch(() => {});
+		throw error;
+	}
 	return client;
 }
 //#endregion
-export { DbCloseError, DbError, DbExecutionError, DbInitializationError, DbTabLockError, createDbClient, defaultExecutor, runMigrations };
+export { DbCloseError, DbError, DbExecutionError, DbInitializationError, DbMigrationError, DbTabLockError, createDbClient, defaultExecutor, runMigrations };

package/dist/{errors-D9KnLHTp.js → errors-DwJZz1Jx.js}

@@ -23,6 +23,20 @@ var DbExecutionError = class extends DbError {
 		this.name = "DbExecutionError";
 	}
 };
+/**
+* 某条迁移执行失败。version 指出失败的是哪个迁移版本，cause 是底层原始错误
+* （通常是 DbExecutionError）。runMigrations 会把 executor 抛出的非 DbMigrationError
+* 错误统一包装成这个类型再向上抛。
+*/
+var DbMigrationError = class extends DbError {
+	version;
+	constructor(version, cause) {
+		const detail = cause instanceof Error ? cause.message : cause === void 0 ? "" : String(cause);
+		super(`Migration ${version} failed${detail ? `: ${detail.slice(0, 500)}` : ""}`, cause);
+		this.version = version;
+		this.name = "DbMigrationError";
+	}
+};
 var DbCloseError = class extends DbError {
 	constructor(cause) {
 		super("Failed to close database", cause);
@@ -41,4 +55,4 @@ var DbTabLockError = class extends DbError {
 	}
 };
 //#endregion
-export { DbTabLockError as a, DbInitializationError as i, DbError as n, DbExecutionError as r, DbCloseError as t };
+export { DbMigrationError as a, DbInitializationError as i, DbError as n, DbTabLockError as o, DbExecutionError as r, DbCloseError as t };

package/dist/react/index.d.ts

@@ -1,4 +1,4 @@
-import { i as DbClient } from "../types-XKvAFU82.js";
+import { a as DbClient } from "../types-Dm9OqT6i.js";
 import React from "react";
 //#region src/react/DatabaseProvider.d.ts
 interface DatabaseContextType {
@@ -14,7 +14,8 @@ interface DatabaseProviderProps {
    *
    * 没有 retry：这个 Promise 只会 settle 一次，重试的语义交给调用方——想重试就在自己的状态
    * 里创建一个新的 client Promise，再把新引用传给这个 prop，effect 依赖 [client] 会自动
-   * 重新走一遍下面的初始化逻辑。
+   * 重新走一遍下面的初始化逻辑。换 promise 的瞬间会先回到完全未就绪状态
+   * （dbClient: null、isDbReady: false），新 promise resolve 之前消费方不会看到旧连接。
    *
    * DatabaseProvider 不拥有 client 的生命周期，卸载时也不会调用 client.close()：谁创建
    * 的 client 谁负责关闭。如果 close() 交给这里，而调用方（比如应用级单例的

package/dist/react/index.js

@@ -9,6 +9,8 @@ const DatabaseProvider = ({ client, children }) => {
 	const [dbError, setDbError] = useState(null);
 	useEffect(() => {
 		let cancelled = false;
+		setDbClient(null);
+		setIsDbReady(false);
 		setIsLoading(true);
 		setDbError(null);
 		Promise.resolve(client).then((resolvedClient) => {

package/dist/types-Dm9OqT6i.d.ts

@@ -0,0 +1,93 @@
+//#region src/core/types.d.ts
+/**
+ * 库内部诊断信息的输出通道。默认是 console；生产应用可以传入自己的实现，
+ * 把告警/错误接入自己的日志系统或静默掉。
+ */
+interface Logger {
+  warn(message: string, ...args: unknown[]): void;
+  error(message: string, ...args: unknown[]): void;
+}
+/** executeBatch 的一条语句：纯 SQL 字符串，或带绑定参数的对象形式 */
+type BatchStatement = string | {
+  sql: string;
+  params?: unknown[];
+};
+interface DbClient {
+  select<T>(sql: string, params?: unknown[]): Promise<T[]>;
+  execute(sql: string, params?: unknown[]): Promise<{
+    lastInsertId?: number;
+    rowsAffected?: number;
+  }>;
+  /**
+   * 顺序执行一批语句，无跨语句事务保证（库目前不提供业务侧事务 API：连接池型适配器
+   * 无法保证 BEGIN/COMMIT 落在同一物理连接上，业务多语句写入请自行保证幂等）。
+   * 全部语句不带 params 时，web/memory 适配器会把它们拼成一条 SQL 一次性发给底层引擎
+   * （web 侧省掉每条一次的 worker 往返）；只要批内有任何一条带参语句，整批退化为逐条执行。
+   * 注意：拼接路径失败时 DbExecutionError.sql 是拼接后的整条 SQL，无法指出失败的是第几句；
+   * 需要精确定位就自己逐条 execute()。
+   */
+  executeBatch(statements: BatchStatement[]): Promise<void>;
+  close(): Promise<void>;
+}
+interface DbAdapterConfig {
+  /** 数据库文件名/标识，如 "my-app"（不含扩展名） */
+  name: string;
+}
+interface DbAdapter {
+  /**
+   * 初始化并返回 client。并发或重复调用共享同一个进行中的初始化（去重），
+   * config 以首次调用为准；close() 之后再调用会重开一个全新连接。
+   */
+  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[];
+}
+/**
+ * 迁移执行器。内部手写 BEGIN/COMMIT 的 executor 必须把 requiresSingleConnection 设为
+ * true（如 adapters/web 的 transactionalExecutor）：createDbClient 会拒绝把它用在
+ * singleConnection !== true 的适配器上。完全不碰事务的 executor（比如只加日志）不需要
+ * 这个标记。
+ * 约定：executor 不要自行抛 DbMigrationError——失败时抛底层错误即可，version 由
+ * runMigrations 统一包装填充。
+ */
+interface MigrationExecutor {
+  (db: Pick<DbClient, "execute" | "select" | "executeBatch">, migration: Migration,
+  /** 记录 schema_version 的回调；executor 决定何时调用（比如放进自己的事务里） */
+  recordVersion: () => Promise<void>): Promise<void>;
+  /** true 表示该 executor 手写 BEGIN/COMMIT，仅可用于 singleConnection === true 的适配器 */
+  requiresSingleConnection?: boolean;
+}
+interface MigrationOptions {
+  /** schema 版本表名，默认 "schema_version"；仅限字母/数字/下划线且不以数字开头 */
+  tableName?: string;
+  /** 自定义执行策略，见 MigrationExecutor */
+  executor?: MigrationExecutor;
+  /** 迁移过程中的诊断输出（如"数据库版本高于当前应用"告警），默认 console */
+  logger?: Logger;
+}
+interface CreateDbClientOptions {
+  name: string;
+  /** 必须显式传入实例，库不提供 'auto'/'web'/'tauri' 字符串快捷方式 */
+  adapter: DbAdapter;
+  migrations?: Migration[];
+  migrationOptions?: MigrationOptions;
+  /**
+   * initialize 之后、迁移之前执行的 PRAGMA 配置，如 { foreign_keys: true, journal_mode: "WAL" }。
+   * key 仅限字母/数字/下划线；string 值仅限字母/数字/下划线（覆盖 WAL、NORMAL 这类枚举值），
+   * boolean 会转成 0/1。非法的 key/value 会直接抛错而不是拼进 SQL。
+   */
+  pragmas?: Record<string, string | number | boolean>;
+  /** 诊断输出通道，默认 console；被 migrationOptions.logger 覆盖（迁移阶段） */
+  logger?: Logger;
+}
+//#endregion
+export { DbClient as a, MigrationExecutor as c, DbAdapterConfig as i, MigrationOptions as l, CreateDbClientOptions as n, Logger as o, DbAdapter as r, Migration as s, BatchStatement as t };

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "cross-sqlite-client",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
+  "sideEffects": false,
   "description": "Cross-platform (Web + Tauri) SQLite client with a shared migration framework and React bindings.",
   "license": "MIT",
   "author": "ueaner",
@@ -41,17 +42,12 @@
     "./react": {
       "types": "./dist/react/index.d.ts",
       "import": "./dist/react/index.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist"
   ],
-  "scripts": {
-    "build": "tsdown",
-    "dev": "tsdown --watch",
-    "test": "vitest run",
-    "lint": "oxlint src test"
-  },
   "peerDependencies": {
     "react": ">=18.0.0"
   },
@@ -65,10 +61,26 @@
     "@tauri-apps/plugin-sql": "^2.4.1"
   },
   "devDependencies": {
+    "@changesets/cli": "^3.0.3",
+    "@testing-library/react": "^16.3.3",
     "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.3.0",
+    "jsdom": "^30.1.0",
+    "oxlint": "^1.83.0",
+    "publint": "^0.3.24",
     "react": "^19.2.8",
+    "react-dom": "^19.3.0",
     "tsdown": "^0.23.0",
     "typescript": "^7.0.2",
     "vitest": "^5.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint src test",
+    "pub:check": "publint",
+    "changeset": "changeset"
   }
-}
+}