@weapp-sqlite/wasm 0.1.1 → 0.2.0

package/README.md

@@ -3,10 +3,11 @@
 可注入 SQLite WASM 引擎和持久化回调的宿主无关 adapter。它连接 sql.js 一类的 WASM 引擎与 `@weapp-sqlite/core`，本身不选择存储宿主。
 
 ```bash
-pnpm add @weapp-sqlite/wasm @weapp-sqlite/core
+pnpm add @weapp-sqlite/wasm @weapp-sqlite/core @weapp-sqlite/sqljs
 ```
 
 ```ts
+import initializer from '@weapp-sqlite/sqljs/full'
 import { openSqliteWasmDatabase } from '@weapp-sqlite/wasm'
 
 const database = await openSqliteWasmDatabase(
@@ -20,6 +21,12 @@ const database = await openSqliteWasmDatabase(
 
 `storage` 至少实现 `load(name)` 和 `save(name, bytes)`；连接的 `flush()` 会在写入后导出最新数据库快照。需要自定义资源路径时传入 `locateFile`。
 
+自定义引擎必须提供 `exportSnapshot(): Uint8Array`，复制主数据库时不得关闭或重建连接。官方原版 sql.js 的 `export()` 不满足这一要求；可迁移到 `@weapp-sqlite/sqljs/full` 或 `/lite`。初始化失败后可以重试。
+
+内置引擎的 `execWithMetadata()` 使用 SQLite 原生只读信息判断写入，`query('INSERT … RETURNING …')` 也会持久化；普通 SELECT 不保存快照。自定义引擎缺少该可选接口时，adapter 将执行保守地视作写入。事务内不会提前持久化，提交后统一保存。
+
+`bigint` 参数仅允许 JavaScript 安全整数范围，超出时抛出 `RangeError`，避免静默舍入。保存失败保留待保存状态，可重试 `flush()`；事务提交后的失败使用 core 的 `SqlitePersistenceError` 表示。完整迁移步骤见[升级指南](https://sqlite.weapp.dev/docs/upgrading)。
+
 本包不直接访问 IndexedDB、小程序文件系统或平台 runtime。Web 使用 `@weapp-sqlite/web`，小程序使用 `@weapp-sqlite/miniprogram`，weapp-vite 项目优先使用 `@weapp-sqlite/weapp-vite`。
 
 通常不需要直接配置 WASM adapter：weapp-vite 会为当前目标自动选择资源。详见 [WASM API](https://sqlite.weapp.dev/docs/api/wasm)。

package/dist/index.cjs

@@ -2,7 +2,10 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let _weapp_sqlite_core = require("@weapp-sqlite/core");
 //#region src/driver.ts
 function normalizeScalar(value) {
-	if (typeof value === "bigint") return Number(value);
+	if (typeof value === "bigint") {
+		if (value < BigInt(Number.MIN_SAFE_INTEGER) || value > BigInt(Number.MAX_SAFE_INTEGER)) throw new RangeError("SQLite WASM bigint parameters must be within the JavaScript safe integer range.");
+		return Number(value);
+	}
 	if (typeof value === "boolean") return value ? 1 : 0;
 	if (value instanceof ArrayBuffer) return new Uint8Array(value);
 	return value;
@@ -25,11 +28,27 @@ function rowsFromResult(result) {
 	};
 }
 function createConnection(database, name, storage) {
-	let dirty = false;
+	let revision = 0;
+	let savedRevision = 0;
+	let saving = Promise.resolve();
+	function execute(sql, parameters, fallback) {
+		const normalized = normalizeParameters(parameters);
+		const previousRevision = revision;
+		revision += 1;
+		if (database.execWithMetadata) {
+			const execution = database.execWithMetadata(sql, normalized);
+			if (execution.readOnly) revision = previousRevision;
+			return execution.results;
+		}
+		if (fallback === "run") {
+			database.run(sql, normalized);
+			return [];
+		}
+		return database.exec(sql, normalized);
+	}
 	return {
 		async exec(sql, parameters) {
-			database.run(sql, normalizeParameters(parameters));
-			dirty = true;
+			execute(sql, parameters, "run");
 			const row = database.exec("SELECT changes() AS changes, last_insert_rowid() AS lastInsertRowid")[0]?.values[0];
 			return {
 				changes: Number(row?.[0] ?? 0),
@@ -37,16 +56,21 @@ function createConnection(database, name, storage) {
 			};
 		},
 		async query(sql, parameters) {
-			const result = database.exec(sql, normalizeParameters(parameters))[0];
+			const result = execute(sql, parameters, "exec")[0];
 			return result ? rowsFromResult(result) : {
 				columns: [],
 				rows: []
 			};
 		},
-		async flush() {
-			if (!dirty) return;
-			await storage.save(name, database.export());
-			dirty = false;
+		flush() {
+			const operation = saving.then(async () => {
+				if (revision === savedRevision) return;
+				const snapshotRevision = revision;
+				await storage.save(name, database.exportSnapshot());
+				savedRevision = snapshotRevision;
+			});
+			saving = operation.catch(() => void 0);
+			return operation;
 		},
 		async close() {
 			database.close();
@@ -58,10 +82,26 @@ function createSqliteWasmDriver(initializer, options) {
 	return {
 		kind: "wasm",
 		async open(name) {
-			modulePromise ??= initializer(options.locateFile ? { locateFile: options.locateFile } : void 0);
+			if (!modulePromise) {
+				const pending = Promise.resolve().then(() => initializer(options.locateFile ? { locateFile: options.locateFile } : void 0));
+				modulePromise = pending;
+				pending.catch(() => {
+					if (modulePromise === pending) modulePromise = void 0;
+				});
+			}
 			const module = await modulePromise;
 			const data = await options.storage.load(name);
-			return createConnection(new module.Database(data), name, options.storage);
+			const database = new module.Database(data);
+			if (typeof database.exportSnapshot !== "function") {
+				const error = /* @__PURE__ */ new TypeError("SQLite WASM engines must implement exportSnapshot() without resetting the connection. Use @weapp-sqlite/sqljs or migrate the custom initializer.");
+				try {
+					database.close();
+				} catch (closeError) {
+					throw new AggregateError([error, closeError], error.message, { cause: error });
+				}
+				throw error;
+			}
+			return createConnection(database, name, options.storage);
 		}
 	};
 }

package/dist/index.d.cts

@@ -6,10 +6,18 @@ interface SqlJsResult {
   readonly columns: readonly string[];
   readonly values: readonly (readonly unknown[])[];
 }
+interface SqlJsExecutionResult {
+  readonly results: readonly SqlJsResult[];
+  readonly readOnly: boolean;
+}
 interface SqlJsDatabase {
   run: (sql: string, parameters?: SqlJsParameters) => SqlJsDatabase;
   exec: (sql: string, parameters?: SqlJsParameters) => readonly SqlJsResult[];
   export: () => Uint8Array;
+  /** Copies the main database without closing or resetting the connection. */
+  exportSnapshot: () => Uint8Array;
+  /** Without metadata, the adapter conservatively treats queries as writes. */
+  execWithMetadata?: (sql: string, parameters?: SqlJsParameters) => SqlJsExecutionResult;
   close: () => void;
 }
 interface SqlJsModule {
@@ -29,7 +37,7 @@ interface SqliteWasmDriverOptions {
 type SqliteWasmParameters = SqliteParameters;
 //#endregion
 //#region src/driver.d.ts
-declare function createSqliteWasmDriver(initializer: SqlJsInitializer, options: SqliteWasmDriverOptions): SqliteDriver;
-declare function openSqliteWasmDatabase(initializer: SqlJsInitializer, name: string, options: SqliteWasmDriverOptions): Promise<SqliteDatabase>;
+export declare function createSqliteWasmDriver(initializer: SqlJsInitializer, options: SqliteWasmDriverOptions): SqliteDriver;
+export declare function openSqliteWasmDatabase(initializer: SqlJsInitializer, name: string, options: SqliteWasmDriverOptions): Promise<SqliteDatabase>;
 //#endregion
-export { type SqlJsDatabase, type SqlJsInitializer, type SqlJsModule, type SqlJsParameters, type SqlJsResult, type SqlJsScalar, type SqliteWasmDriverOptions, type SqliteWasmParameters, type SqliteWasmStorage, createSqliteWasmDriver, openSqliteWasmDatabase };
+export type { SqlJsDatabase, SqlJsExecutionResult, SqlJsInitializer, SqlJsModule, SqlJsParameters, SqlJsResult, SqlJsScalar, SqliteWasmDriverOptions, SqliteWasmParameters, SqliteWasmStorage };

package/dist/index.d.mts

@@ -6,10 +6,18 @@ interface SqlJsResult {
   readonly columns: readonly string[];
   readonly values: readonly (readonly unknown[])[];
 }
+interface SqlJsExecutionResult {
+  readonly results: readonly SqlJsResult[];
+  readonly readOnly: boolean;
+}
 interface SqlJsDatabase {
   run: (sql: string, parameters?: SqlJsParameters) => SqlJsDatabase;
   exec: (sql: string, parameters?: SqlJsParameters) => readonly SqlJsResult[];
   export: () => Uint8Array;
+  /** Copies the main database without closing or resetting the connection. */
+  exportSnapshot: () => Uint8Array;
+  /** Without metadata, the adapter conservatively treats queries as writes. */
+  execWithMetadata?: (sql: string, parameters?: SqlJsParameters) => SqlJsExecutionResult;
   close: () => void;
 }
 interface SqlJsModule {
@@ -29,7 +37,7 @@ interface SqliteWasmDriverOptions {
 type SqliteWasmParameters = SqliteParameters;
 //#endregion
 //#region src/driver.d.ts
-declare function createSqliteWasmDriver(initializer: SqlJsInitializer, options: SqliteWasmDriverOptions): SqliteDriver;
-declare function openSqliteWasmDatabase(initializer: SqlJsInitializer, name: string, options: SqliteWasmDriverOptions): Promise<SqliteDatabase>;
+export declare function createSqliteWasmDriver(initializer: SqlJsInitializer, options: SqliteWasmDriverOptions): SqliteDriver;
+export declare function openSqliteWasmDatabase(initializer: SqlJsInitializer, name: string, options: SqliteWasmDriverOptions): Promise<SqliteDatabase>;
 //#endregion
-export { type SqlJsDatabase, type SqlJsInitializer, type SqlJsModule, type SqlJsParameters, type SqlJsResult, type SqlJsScalar, type SqliteWasmDriverOptions, type SqliteWasmParameters, type SqliteWasmStorage, createSqliteWasmDriver, openSqliteWasmDatabase };
+export type { SqlJsDatabase, SqlJsExecutionResult, SqlJsInitializer, SqlJsModule, SqlJsParameters, SqlJsResult, SqlJsScalar, SqliteWasmDriverOptions, SqliteWasmParameters, SqliteWasmStorage };

package/dist/index.mjs

@@ -1,7 +1,10 @@
 import { createSqliteDatabase } from "@weapp-sqlite/core";
 //#region src/driver.ts
 function normalizeScalar(value) {
-	if (typeof value === "bigint") return Number(value);
+	if (typeof value === "bigint") {
+		if (value < BigInt(Number.MIN_SAFE_INTEGER) || value > BigInt(Number.MAX_SAFE_INTEGER)) throw new RangeError("SQLite WASM bigint parameters must be within the JavaScript safe integer range.");
+		return Number(value);
+	}
 	if (typeof value === "boolean") return value ? 1 : 0;
 	if (value instanceof ArrayBuffer) return new Uint8Array(value);
 	return value;
@@ -24,11 +27,27 @@ function rowsFromResult(result) {
 	};
 }
 function createConnection(database, name, storage) {
-	let dirty = false;
+	let revision = 0;
+	let savedRevision = 0;
+	let saving = Promise.resolve();
+	function execute(sql, parameters, fallback) {
+		const normalized = normalizeParameters(parameters);
+		const previousRevision = revision;
+		revision += 1;
+		if (database.execWithMetadata) {
+			const execution = database.execWithMetadata(sql, normalized);
+			if (execution.readOnly) revision = previousRevision;
+			return execution.results;
+		}
+		if (fallback === "run") {
+			database.run(sql, normalized);
+			return [];
+		}
+		return database.exec(sql, normalized);
+	}
 	return {
 		async exec(sql, parameters) {
-			database.run(sql, normalizeParameters(parameters));
-			dirty = true;
+			execute(sql, parameters, "run");
 			const row = database.exec("SELECT changes() AS changes, last_insert_rowid() AS lastInsertRowid")[0]?.values[0];
 			return {
 				changes: Number(row?.[0] ?? 0),
@@ -36,16 +55,21 @@ function createConnection(database, name, storage) {
 			};
 		},
 		async query(sql, parameters) {
-			const result = database.exec(sql, normalizeParameters(parameters))[0];
+			const result = execute(sql, parameters, "exec")[0];
 			return result ? rowsFromResult(result) : {
 				columns: [],
 				rows: []
 			};
 		},
-		async flush() {
-			if (!dirty) return;
-			await storage.save(name, database.export());
-			dirty = false;
+		flush() {
+			const operation = saving.then(async () => {
+				if (revision === savedRevision) return;
+				const snapshotRevision = revision;
+				await storage.save(name, database.exportSnapshot());
+				savedRevision = snapshotRevision;
+			});
+			saving = operation.catch(() => void 0);
+			return operation;
 		},
 		async close() {
 			database.close();
@@ -57,10 +81,26 @@ function createSqliteWasmDriver(initializer, options) {
 	return {
 		kind: "wasm",
 		async open(name) {
-			modulePromise ??= initializer(options.locateFile ? { locateFile: options.locateFile } : void 0);
+			if (!modulePromise) {
+				const pending = Promise.resolve().then(() => initializer(options.locateFile ? { locateFile: options.locateFile } : void 0));
+				modulePromise = pending;
+				pending.catch(() => {
+					if (modulePromise === pending) modulePromise = void 0;
+				});
+			}
 			const module = await modulePromise;
 			const data = await options.storage.load(name);
-			return createConnection(new module.Database(data), name, options.storage);
+			const database = new module.Database(data);
+			if (typeof database.exportSnapshot !== "function") {
+				const error = /* @__PURE__ */ new TypeError("SQLite WASM engines must implement exportSnapshot() without resetting the connection. Use @weapp-sqlite/sqljs or migrate the custom initializer.");
+				try {
+					database.close();
+				} catch (closeError) {
+					throw new AggregateError([error, closeError], error.message, { cause: error });
+				}
+				throw error;
+			}
+			return createConnection(database, name, options.storage);
 		}
 	};
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@weapp-sqlite/wasm",
   "type": "module",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "基于可注入 WASM SQLite 引擎的跨宿主 adapter",
   "author": "weapp-sqlite contributors",
   "license": "MIT",
@@ -45,16 +45,12 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@weapp-sqlite/core": "0.1.1"
+    "@weapp-sqlite/core": "0.2.0"
   },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "devDependencies": {
-    "@types/sql.js": "^1.4.11",
-    "sql.js": "^1.14.2"
-  },
   "scripts": {
     "dev": "tsdown -w",
     "build": "tsdown",
@@ -64,6 +60,6 @@
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "typecheck": "tsc -p tsconfig.json",
-    "tsd": "pnpm build && tsd --files test-d/**/*.test-d.ts"
+    "tsd": "pnpm build && tsd --typings dist/index.d.mts --files test-d/**/*.test-d.ts"
   }
 }