@monlite/wasm 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emad Jumaah
+
+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,70 @@
+# @monlite/wasm
+
+Run [`@monlite/core`](https://www.npmjs.com/package/@monlite/core) **in the browser** (or anywhere) on SQLite compiled to WebAssembly, via [sql.js](https://sql.js.org). monlite's driver-adapter seam means the browser is just another backend — the document/structured query API, reactivity, and the kv/queue/cron harness all run unchanged.
+
+```bash
+npm install @monlite/core @monlite/wasm sql.js
+```
+
+## Quick start
+
+`initSqlJs` is async (it loads the `.wasm`), so initialise it first, then hand the
+module to `wasmDriver` — `createDb` itself stays synchronous:
+
+```ts
+import initSqlJs from "sql.js";
+import { createDb } from "@monlite/core";
+import { wasmDriver } from "@monlite/wasm";
+
+const SQL = await initSqlJs({
+  // point at where your bundler serves sql-wasm.wasm
+  locateFile: (file) => `/sqljs/${file}`,
+});
+
+const db = createDb(":memory:", { driver: wasmDriver(SQL) });
+
+await db.collection("notes").create({ data: { title: "hello", body: "from the browser" } });
+const notes = await db.collection("notes").findMany({ where: { title: "hello" } });
+```
+
+> Bundlers: copy `node_modules/sql.js/dist/sql-wasm.wasm` to a served path and
+> return it from `locateFile`. (Vite: put it in `public/sqljs/`.)
+
+## Persistence
+
+sql.js holds the database in memory. Persist it by **snapshotting the bytes** to
+IndexedDB (or OPFS) and reopening from them — `exportDatabase()` gives you the
+bytes, and `wasmDriver(SQL, { data })` restores them:
+
+```ts
+import { wasmDriver, exportDatabase } from "@monlite/wasm";
+
+// On startup: restore previous bytes (your IndexedDB getter), if any.
+const saved = await idbGet("monlite-db"); // Uint8Array | undefined
+const db = createDb(":memory:", { driver: wasmDriver(SQL, { data: saved }) });
+
+// After writes (debounced) or on `beforeunload`: snapshot back.
+async function persist() {
+  await idbSet("monlite-db", exportDatabase(db));
+}
+```
+
+A small reactive debounce works well: persist after a quiet period following any
+write (e.g. subscribe with `collection.watch(...)` and call `persist()` on a
+trailing debounce).
+
+### Roadmap: incremental OPFS persistence
+
+Snapshotting rewrites the whole file, which is fine up to tens of MB. For larger,
+write-heavy databases the planned next step is a driver over the **official
+`@sqlite.org/sqlite-wasm` with the OPFS VFS** (running in a Web Worker with
+synchronous access handles), which persists **incrementally** — no full-file
+re-export. Same `Driver` seam, drop-in. (Tracked on the roadmap.)
+
+## Notes
+
+- sql.js runs in Node as well, so this driver is covered by the normal test suite.
+- A monlite WASM database is the same SQLite format as the Node backends, so it
+  syncs with a server (or another device) through [`@monlite/sync`](https://www.npmjs.com/package/@monlite/sync) like any other monlite database.
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,102 @@
+'use strict';
+
+// src/index.ts
+var WasmDriver = class {
+  name = "wasm-sqlite";
+  raw;
+  cache = /* @__PURE__ */ new Map();
+  depth = 0;
+  constructor(SQL, options = {}) {
+    this.raw = new SQL.Database(options.data ?? null);
+    this.raw.run("PRAGMA foreign_keys = ON");
+  }
+  exec(sql) {
+    this.raw.run(sql);
+  }
+  lastInsertRowid() {
+    const res = this.raw.exec("SELECT last_insert_rowid() AS id");
+    return res[0]?.values?.[0]?.[0] ?? 0;
+  }
+  prepare(sql) {
+    const cached = this.cache.get(sql);
+    if (cached) return cached.wrapped;
+    const stmt = this.raw.prepare(sql);
+    const wrapped = {
+      run: (...params) => {
+        stmt.run(params);
+        return {
+          changes: this.raw.getRowsModified(),
+          lastInsertRowid: this.lastInsertRowid()
+        };
+      },
+      get: (...params) => {
+        stmt.bind(params);
+        const row = stmt.step() ? stmt.getAsObject() : void 0;
+        stmt.reset();
+        return row;
+      },
+      all: (...params) => {
+        stmt.bind(params);
+        const rows = [];
+        while (stmt.step()) rows.push(stmt.getAsObject());
+        stmt.reset();
+        return rows;
+      }
+    };
+    this.cache.set(sql, { stmt, wrapped });
+    return wrapped;
+  }
+  transaction(fn) {
+    const savepoint = `monlite_sp_${this.depth}`;
+    if (this.depth === 0) this.raw.run("BEGIN");
+    else this.raw.run(`SAVEPOINT ${savepoint}`);
+    this.depth++;
+    try {
+      const result = fn();
+      this.depth--;
+      if (this.depth === 0) this.raw.run("COMMIT");
+      else this.raw.run(`RELEASE ${savepoint}`);
+      return result;
+    } catch (err) {
+      this.depth--;
+      try {
+        if (this.depth === 0) this.raw.run("ROLLBACK");
+        else this.raw.run(`ROLLBACK TO ${savepoint}; RELEASE ${savepoint}`);
+      } catch {
+        this.depth = 0;
+        try {
+          this.raw.run("ROLLBACK");
+        } catch {
+        }
+      }
+      throw err;
+    }
+  }
+  /** Serialize the whole database to bytes (for persistence). */
+  export() {
+    return this.raw.export();
+  }
+  close() {
+    for (const { stmt } of this.cache.values()) stmt.free();
+    this.cache.clear();
+    this.raw.close();
+  }
+};
+function wasmDriver(SQL, options) {
+  return new WasmDriver(SQL, options);
+}
+function exportDatabase(db) {
+  const driver = db.driver;
+  if (!(driver instanceof WasmDriver)) {
+    throw new Error(
+      "exportDatabase requires a database opened with the WASM driver"
+    );
+  }
+  return driver.export();
+}
+
+exports.WasmDriver = WasmDriver;
+exports.exportDatabase = exportDatabase;
+exports.wasmDriver = wasmDriver;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["import type { Driver, PreparedStatement, RunResult } from \"@monlite/core\";\n\n/**\n * The subset of the sql.js module/`Database` we rely on. Passing `sql.js`'s\n * `SqlJsStatic` (the result of `initSqlJs()`) satisfies this.\n */\nexport interface SqlJsStatic {\n  Database: new (data?: Uint8Array | null) => SqlJsDatabase;\n}\nexport interface SqlJsDatabase {\n  run(sql: string, params?: any[]): void;\n  prepare(sql: string): SqlJsStatement;\n  exec(sql: string): Array<{ columns: string[]; values: any[][] }>;\n  getRowsModified(): number;\n  export(): Uint8Array;\n  close(): void;\n}\nexport interface SqlJsStatement {\n  bind(params?: any[]): boolean;\n  step(): boolean;\n  getAsObject(): Record<string, any>;\n  run(params?: any[]): void;\n  reset(): void;\n  free(): void;\n}\n\nexport interface WasmDriverOptions {\n  /** Existing database bytes to open (e.g. restored from IndexedDB/OPFS). */\n  data?: Uint8Array | null;\n}\n\n/**\n * A monlite {@link Driver} backed by SQLite-WASM (sql.js). Runs in the browser\n * (and Node). Construction is synchronous — initialise sql.js yourself first:\n *\n * ```ts\n * import initSqlJs from \"sql.js\";\n * import { wasmDriver } from \"@monlite/wasm\";\n * import { createDb } from \"@monlite/core\";\n *\n * const SQL = await initSqlJs({ locateFile: (f) => `/sqljs/${f}` });\n * const db = createDb(\":memory:\", { driver: wasmDriver(SQL) });\n * ```\n *\n * sql.js is in-memory; use {@link exportDatabase}/`{ data }` to persist (see the\n * README for IndexedDB/OPFS recipes).\n */\nexport class WasmDriver implements Driver {\n  readonly name = \"wasm-sqlite\";\n  readonly raw: SqlJsDatabase;\n  private readonly cache = new Map<\n    string,\n    { stmt: SqlJsStatement; wrapped: PreparedStatement }\n  >();\n  private depth = 0;\n\n  constructor(SQL: SqlJsStatic, options: WasmDriverOptions = {}) {\n    this.raw = new SQL.Database(options.data ?? null);\n    this.raw.run(\"PRAGMA foreign_keys = ON\");\n  }\n\n  exec(sql: string): void {\n    this.raw.run(sql);\n  }\n\n  private lastInsertRowid(): number {\n    const res = this.raw.exec(\"SELECT last_insert_rowid() AS id\");\n    return (res[0]?.values?.[0]?.[0] as number) ?? 0;\n  }\n\n  prepare(sql: string): PreparedStatement {\n    const cached = this.cache.get(sql);\n    if (cached) return cached.wrapped;\n\n    const stmt = this.raw.prepare(sql);\n    // Arrow functions capture the driver's `this` lexically.\n    const wrapped: PreparedStatement = {\n      run: (...params: any[]): RunResult => {\n        stmt.run(params);\n        return {\n          changes: this.raw.getRowsModified(),\n          lastInsertRowid: this.lastInsertRowid(),\n        };\n      },\n      get: (...params: any[]): any => {\n        stmt.bind(params);\n        const row = stmt.step() ? stmt.getAsObject() : undefined;\n        stmt.reset();\n        return row;\n      },\n      all: (...params: any[]): any[] => {\n        stmt.bind(params);\n        const rows: any[] = [];\n        while (stmt.step()) rows.push(stmt.getAsObject());\n        stmt.reset();\n        return rows;\n      },\n    };\n    this.cache.set(sql, { stmt, wrapped });\n    return wrapped;\n  }\n\n  transaction<T>(fn: () => T): T {\n    const savepoint = `monlite_sp_${this.depth}`;\n    if (this.depth === 0) this.raw.run(\"BEGIN\");\n    else this.raw.run(`SAVEPOINT ${savepoint}`);\n    this.depth++;\n    try {\n      const result = fn();\n      this.depth--;\n      if (this.depth === 0) this.raw.run(\"COMMIT\");\n      else this.raw.run(`RELEASE ${savepoint}`);\n      return result;\n    } catch (err) {\n      this.depth--;\n      try {\n        if (this.depth === 0) this.raw.run(\"ROLLBACK\");\n        else this.raw.run(`ROLLBACK TO ${savepoint}; RELEASE ${savepoint}`);\n      } catch {\n        this.depth = 0;\n        try {\n          this.raw.run(\"ROLLBACK\");\n        } catch {\n          /* no active transaction */\n        }\n      }\n      throw err;\n    }\n  }\n\n  /** Serialize the whole database to bytes (for persistence). */\n  export(): Uint8Array {\n    return this.raw.export();\n  }\n\n  close(): void {\n    for (const { stmt } of this.cache.values()) stmt.free();\n    this.cache.clear();\n    this.raw.close();\n  }\n}\n\n/** Create a WASM-backed monlite driver from an initialised sql.js module. */\nexport function wasmDriver(\n  SQL: SqlJsStatic,\n  options?: WasmDriverOptions,\n): WasmDriver {\n  return new WasmDriver(SQL, options);\n}\n\n/**\n * Serialize a monlite database opened with the WASM driver to bytes — persist\n * these (IndexedDB/OPFS/file) and reopen with `wasmDriver(SQL, { data })`.\n */\nexport function exportDatabase(db: { driver: Driver }): Uint8Array {\n  const driver = db.driver;\n  if (!(driver instanceof WasmDriver)) {\n    throw new Error(\n      \"exportDatabase requires a database opened with the WASM driver\",\n    );\n  }\n  return driver.export();\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,73 @@
+import { Driver, PreparedStatement } from '@monlite/core';
+
+/**
+ * The subset of the sql.js module/`Database` we rely on. Passing `sql.js`'s
+ * `SqlJsStatic` (the result of `initSqlJs()`) satisfies this.
+ */
+interface SqlJsStatic {
+    Database: new (data?: Uint8Array | null) => SqlJsDatabase;
+}
+interface SqlJsDatabase {
+    run(sql: string, params?: any[]): void;
+    prepare(sql: string): SqlJsStatement;
+    exec(sql: string): Array<{
+        columns: string[];
+        values: any[][];
+    }>;
+    getRowsModified(): number;
+    export(): Uint8Array;
+    close(): void;
+}
+interface SqlJsStatement {
+    bind(params?: any[]): boolean;
+    step(): boolean;
+    getAsObject(): Record<string, any>;
+    run(params?: any[]): void;
+    reset(): void;
+    free(): void;
+}
+interface WasmDriverOptions {
+    /** Existing database bytes to open (e.g. restored from IndexedDB/OPFS). */
+    data?: Uint8Array | null;
+}
+/**
+ * A monlite {@link Driver} backed by SQLite-WASM (sql.js). Runs in the browser
+ * (and Node). Construction is synchronous — initialise sql.js yourself first:
+ *
+ * ```ts
+ * import initSqlJs from "sql.js";
+ * import { wasmDriver } from "@monlite/wasm";
+ * import { createDb } from "@monlite/core";
+ *
+ * const SQL = await initSqlJs({ locateFile: (f) => `/sqljs/${f}` });
+ * const db = createDb(":memory:", { driver: wasmDriver(SQL) });
+ * ```
+ *
+ * sql.js is in-memory; use {@link exportDatabase}/`{ data }` to persist (see the
+ * README for IndexedDB/OPFS recipes).
+ */
+declare class WasmDriver implements Driver {
+    readonly name = "wasm-sqlite";
+    readonly raw: SqlJsDatabase;
+    private readonly cache;
+    private depth;
+    constructor(SQL: SqlJsStatic, options?: WasmDriverOptions);
+    exec(sql: string): void;
+    private lastInsertRowid;
+    prepare(sql: string): PreparedStatement;
+    transaction<T>(fn: () => T): T;
+    /** Serialize the whole database to bytes (for persistence). */
+    export(): Uint8Array;
+    close(): void;
+}
+/** Create a WASM-backed monlite driver from an initialised sql.js module. */
+declare function wasmDriver(SQL: SqlJsStatic, options?: WasmDriverOptions): WasmDriver;
+/**
+ * Serialize a monlite database opened with the WASM driver to bytes — persist
+ * these (IndexedDB/OPFS/file) and reopen with `wasmDriver(SQL, { data })`.
+ */
+declare function exportDatabase(db: {
+    driver: Driver;
+}): Uint8Array;
+
+export { type SqlJsDatabase, type SqlJsStatement, type SqlJsStatic, WasmDriver, type WasmDriverOptions, exportDatabase, wasmDriver };

package/dist/index.d.ts

@@ -0,0 +1,73 @@
+import { Driver, PreparedStatement } from '@monlite/core';
+
+/**
+ * The subset of the sql.js module/`Database` we rely on. Passing `sql.js`'s
+ * `SqlJsStatic` (the result of `initSqlJs()`) satisfies this.
+ */
+interface SqlJsStatic {
+    Database: new (data?: Uint8Array | null) => SqlJsDatabase;
+}
+interface SqlJsDatabase {
+    run(sql: string, params?: any[]): void;
+    prepare(sql: string): SqlJsStatement;
+    exec(sql: string): Array<{
+        columns: string[];
+        values: any[][];
+    }>;
+    getRowsModified(): number;
+    export(): Uint8Array;
+    close(): void;
+}
+interface SqlJsStatement {
+    bind(params?: any[]): boolean;
+    step(): boolean;
+    getAsObject(): Record<string, any>;
+    run(params?: any[]): void;
+    reset(): void;
+    free(): void;
+}
+interface WasmDriverOptions {
+    /** Existing database bytes to open (e.g. restored from IndexedDB/OPFS). */
+    data?: Uint8Array | null;
+}
+/**
+ * A monlite {@link Driver} backed by SQLite-WASM (sql.js). Runs in the browser
+ * (and Node). Construction is synchronous — initialise sql.js yourself first:
+ *
+ * ```ts
+ * import initSqlJs from "sql.js";
+ * import { wasmDriver } from "@monlite/wasm";
+ * import { createDb } from "@monlite/core";
+ *
+ * const SQL = await initSqlJs({ locateFile: (f) => `/sqljs/${f}` });
+ * const db = createDb(":memory:", { driver: wasmDriver(SQL) });
+ * ```
+ *
+ * sql.js is in-memory; use {@link exportDatabase}/`{ data }` to persist (see the
+ * README for IndexedDB/OPFS recipes).
+ */
+declare class WasmDriver implements Driver {
+    readonly name = "wasm-sqlite";
+    readonly raw: SqlJsDatabase;
+    private readonly cache;
+    private depth;
+    constructor(SQL: SqlJsStatic, options?: WasmDriverOptions);
+    exec(sql: string): void;
+    private lastInsertRowid;
+    prepare(sql: string): PreparedStatement;
+    transaction<T>(fn: () => T): T;
+    /** Serialize the whole database to bytes (for persistence). */
+    export(): Uint8Array;
+    close(): void;
+}
+/** Create a WASM-backed monlite driver from an initialised sql.js module. */
+declare function wasmDriver(SQL: SqlJsStatic, options?: WasmDriverOptions): WasmDriver;
+/**
+ * Serialize a monlite database opened with the WASM driver to bytes — persist
+ * these (IndexedDB/OPFS/file) and reopen with `wasmDriver(SQL, { data })`.
+ */
+declare function exportDatabase(db: {
+    driver: Driver;
+}): Uint8Array;
+
+export { type SqlJsDatabase, type SqlJsStatement, type SqlJsStatic, WasmDriver, type WasmDriverOptions, exportDatabase, wasmDriver };

package/dist/index.js

@@ -0,0 +1,98 @@
+// src/index.ts
+var WasmDriver = class {
+  name = "wasm-sqlite";
+  raw;
+  cache = /* @__PURE__ */ new Map();
+  depth = 0;
+  constructor(SQL, options = {}) {
+    this.raw = new SQL.Database(options.data ?? null);
+    this.raw.run("PRAGMA foreign_keys = ON");
+  }
+  exec(sql) {
+    this.raw.run(sql);
+  }
+  lastInsertRowid() {
+    const res = this.raw.exec("SELECT last_insert_rowid() AS id");
+    return res[0]?.values?.[0]?.[0] ?? 0;
+  }
+  prepare(sql) {
+    const cached = this.cache.get(sql);
+    if (cached) return cached.wrapped;
+    const stmt = this.raw.prepare(sql);
+    const wrapped = {
+      run: (...params) => {
+        stmt.run(params);
+        return {
+          changes: this.raw.getRowsModified(),
+          lastInsertRowid: this.lastInsertRowid()
+        };
+      },
+      get: (...params) => {
+        stmt.bind(params);
+        const row = stmt.step() ? stmt.getAsObject() : void 0;
+        stmt.reset();
+        return row;
+      },
+      all: (...params) => {
+        stmt.bind(params);
+        const rows = [];
+        while (stmt.step()) rows.push(stmt.getAsObject());
+        stmt.reset();
+        return rows;
+      }
+    };
+    this.cache.set(sql, { stmt, wrapped });
+    return wrapped;
+  }
+  transaction(fn) {
+    const savepoint = `monlite_sp_${this.depth}`;
+    if (this.depth === 0) this.raw.run("BEGIN");
+    else this.raw.run(`SAVEPOINT ${savepoint}`);
+    this.depth++;
+    try {
+      const result = fn();
+      this.depth--;
+      if (this.depth === 0) this.raw.run("COMMIT");
+      else this.raw.run(`RELEASE ${savepoint}`);
+      return result;
+    } catch (err) {
+      this.depth--;
+      try {
+        if (this.depth === 0) this.raw.run("ROLLBACK");
+        else this.raw.run(`ROLLBACK TO ${savepoint}; RELEASE ${savepoint}`);
+      } catch {
+        this.depth = 0;
+        try {
+          this.raw.run("ROLLBACK");
+        } catch {
+        }
+      }
+      throw err;
+    }
+  }
+  /** Serialize the whole database to bytes (for persistence). */
+  export() {
+    return this.raw.export();
+  }
+  close() {
+    for (const { stmt } of this.cache.values()) stmt.free();
+    this.cache.clear();
+    this.raw.close();
+  }
+};
+function wasmDriver(SQL, options) {
+  return new WasmDriver(SQL, options);
+}
+function exportDatabase(db) {
+  const driver = db.driver;
+  if (!(driver instanceof WasmDriver)) {
+    throw new Error(
+      "exportDatabase requires a database opened with the WASM driver"
+    );
+  }
+  return driver.export();
+}
+
+export { WasmDriver, exportDatabase, wasmDriver };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type { Driver, PreparedStatement, RunResult } from \"@monlite/core\";\n\n/**\n * The subset of the sql.js module/`Database` we rely on. Passing `sql.js`'s\n * `SqlJsStatic` (the result of `initSqlJs()`) satisfies this.\n */\nexport interface SqlJsStatic {\n  Database: new (data?: Uint8Array | null) => SqlJsDatabase;\n}\nexport interface SqlJsDatabase {\n  run(sql: string, params?: any[]): void;\n  prepare(sql: string): SqlJsStatement;\n  exec(sql: string): Array<{ columns: string[]; values: any[][] }>;\n  getRowsModified(): number;\n  export(): Uint8Array;\n  close(): void;\n}\nexport interface SqlJsStatement {\n  bind(params?: any[]): boolean;\n  step(): boolean;\n  getAsObject(): Record<string, any>;\n  run(params?: any[]): void;\n  reset(): void;\n  free(): void;\n}\n\nexport interface WasmDriverOptions {\n  /** Existing database bytes to open (e.g. restored from IndexedDB/OPFS). */\n  data?: Uint8Array | null;\n}\n\n/**\n * A monlite {@link Driver} backed by SQLite-WASM (sql.js). Runs in the browser\n * (and Node). Construction is synchronous — initialise sql.js yourself first:\n *\n * ```ts\n * import initSqlJs from \"sql.js\";\n * import { wasmDriver } from \"@monlite/wasm\";\n * import { createDb } from \"@monlite/core\";\n *\n * const SQL = await initSqlJs({ locateFile: (f) => `/sqljs/${f}` });\n * const db = createDb(\":memory:\", { driver: wasmDriver(SQL) });\n * ```\n *\n * sql.js is in-memory; use {@link exportDatabase}/`{ data }` to persist (see the\n * README for IndexedDB/OPFS recipes).\n */\nexport class WasmDriver implements Driver {\n  readonly name = \"wasm-sqlite\";\n  readonly raw: SqlJsDatabase;\n  private readonly cache = new Map<\n    string,\n    { stmt: SqlJsStatement; wrapped: PreparedStatement }\n  >();\n  private depth = 0;\n\n  constructor(SQL: SqlJsStatic, options: WasmDriverOptions = {}) {\n    this.raw = new SQL.Database(options.data ?? null);\n    this.raw.run(\"PRAGMA foreign_keys = ON\");\n  }\n\n  exec(sql: string): void {\n    this.raw.run(sql);\n  }\n\n  private lastInsertRowid(): number {\n    const res = this.raw.exec(\"SELECT last_insert_rowid() AS id\");\n    return (res[0]?.values?.[0]?.[0] as number) ?? 0;\n  }\n\n  prepare(sql: string): PreparedStatement {\n    const cached = this.cache.get(sql);\n    if (cached) return cached.wrapped;\n\n    const stmt = this.raw.prepare(sql);\n    // Arrow functions capture the driver's `this` lexically.\n    const wrapped: PreparedStatement = {\n      run: (...params: any[]): RunResult => {\n        stmt.run(params);\n        return {\n          changes: this.raw.getRowsModified(),\n          lastInsertRowid: this.lastInsertRowid(),\n        };\n      },\n      get: (...params: any[]): any => {\n        stmt.bind(params);\n        const row = stmt.step() ? stmt.getAsObject() : undefined;\n        stmt.reset();\n        return row;\n      },\n      all: (...params: any[]): any[] => {\n        stmt.bind(params);\n        const rows: any[] = [];\n        while (stmt.step()) rows.push(stmt.getAsObject());\n        stmt.reset();\n        return rows;\n      },\n    };\n    this.cache.set(sql, { stmt, wrapped });\n    return wrapped;\n  }\n\n  transaction<T>(fn: () => T): T {\n    const savepoint = `monlite_sp_${this.depth}`;\n    if (this.depth === 0) this.raw.run(\"BEGIN\");\n    else this.raw.run(`SAVEPOINT ${savepoint}`);\n    this.depth++;\n    try {\n      const result = fn();\n      this.depth--;\n      if (this.depth === 0) this.raw.run(\"COMMIT\");\n      else this.raw.run(`RELEASE ${savepoint}`);\n      return result;\n    } catch (err) {\n      this.depth--;\n      try {\n        if (this.depth === 0) this.raw.run(\"ROLLBACK\");\n        else this.raw.run(`ROLLBACK TO ${savepoint}; RELEASE ${savepoint}`);\n      } catch {\n        this.depth = 0;\n        try {\n          this.raw.run(\"ROLLBACK\");\n        } catch {\n          /* no active transaction */\n        }\n      }\n      throw err;\n    }\n  }\n\n  /** Serialize the whole database to bytes (for persistence). */\n  export(): Uint8Array {\n    return this.raw.export();\n  }\n\n  close(): void {\n    for (const { stmt } of this.cache.values()) stmt.free();\n    this.cache.clear();\n    this.raw.close();\n  }\n}\n\n/** Create a WASM-backed monlite driver from an initialised sql.js module. */\nexport function wasmDriver(\n  SQL: SqlJsStatic,\n  options?: WasmDriverOptions,\n): WasmDriver {\n  return new WasmDriver(SQL, options);\n}\n\n/**\n * Serialize a monlite database opened with the WASM driver to bytes — persist\n * these (IndexedDB/OPFS/file) and reopen with `wasmDriver(SQL, { data })`.\n */\nexport function exportDatabase(db: { driver: Driver }): Uint8Array {\n  const driver = db.driver;\n  if (!(driver instanceof WasmDriver)) {\n    throw new Error(\n      \"exportDatabase requires a database opened with the WASM driver\",\n    );\n  }\n  return driver.export();\n}\n"]}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@monlite/wasm",
+  "version": "0.1.0",
+  "description": "Run @monlite/core in the browser (or anywhere) on SQLite-WASM via sql.js — a custom driver.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "monlite",
+    "wasm",
+    "sqlite",
+    "browser",
+    "sql.js",
+    "local-first",
+    "opfs"
+  ],
+  "license": "MIT",
+  "author": "Emad Jumaah <emadjumaah@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/qataruts/monlite.git",
+    "directory": "packages/wasm"
+  },
+  "homepage": "https://github.com/qataruts/monlite/tree/main/packages/wasm#readme",
+  "bugs": {
+    "url": "https://github.com/qataruts/monlite/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@monlite/core": "^1.3.0"
+  },
+  "peerDependencies": {
+    "sql.js": ">=1.8"
+  },
+  "peerDependenciesMeta": {
+    "sql.js": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@types/sql.js": "^1.4.9",
+    "sql.js": "^1.14.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}