Initial Commit

packages/persistence/database/db-sqlite/src/adapter/adapter.wasm.md

@@ -0,0 +1,64 @@
+# adapter.wasm
+
+## Purpose
+
+Browser-runtime entry point for the `./adapter` conditional export in `@suaveplan/db-sqlite`. When a browser bundler resolves `import { createWasmDriver } from "@suaveplan/db-sqlite/adapter"`, this file is selected via the `"browser"` condition in the package's `exports` field. It re-exports the WASM-backed driver factory and its related types, giving browser consumers a clean surface that never references `bun:sqlite` or any Node.js-only API.
+
+The separation between Bun and WASM adapter entry points keeps tree-shaking effective: a Bun server bundle never pulls in `@sqlite.org/sqlite-wasm` or the Web Worker, and a browser bundle never pulls in `bun:sqlite`. Each entry point is resolved at build time by the bundler's condition matching.
+
+## Features
+
+- Conditional export target for the `"browser"` condition in `package.json`
+- Re-exports `createWasmDriver`, `WasmDriverResult`, and `WasmProxyDb` from the WASM driver
+- Re-exports `WasmDriverOptions` type from the shared schemas
+- Zero runtime overhead — pure re-export barrel
+
+## Usage: Basic Example
+
+```ts
+// Resolved automatically by the browser bundler via conditional exports
+import { createWasmDriver } from "@suaveplan/db-sqlite/adapter";
+
+const { db, close } = await createWasmDriver();
+const rows = await db.query("SELECT 1 AS n");
+await close();
+```
+
+## Usage: Advanced Example
+
+```ts
+import { createWasmDriver } from "@suaveplan/db-sqlite/adapter";
+import type { WasmDriverOptions } from "@suaveplan/db-sqlite/adapter";
+
+const opts: WasmDriverOptions = {
+    filename: "app.db",  // OPFS-backed persistent storage
+};
+
+const { db, close } = await createWasmDriver(opts);
+
+await db.execute(
+    "CREATE TABLE IF NOT EXISTS notes (id INTEGER PRIMARY KEY, body TEXT)"
+);
+await db.execute("INSERT INTO notes (body) VALUES (?)", ["Hello from the browser"]);
+
+const rows = await db.query<{ id: number; body: string }>(
+    "SELECT * FROM notes ORDER BY id"
+);
+console.log(rows);
+
+await close();
+```
+
+## API Reference
+
+This file does not export any symbols directly — it is a conditional-export barrel. All types and values are documented in [`../drivers/wasm-driver.md`](../drivers/wasm-driver.md).
+
+**Conditional export condition:** `"browser"` — selected when a bundler uses browser-targeting conditions (e.g. Vite's default, Webpack's `target: "web"`).
+
+**Default fallback:** When neither `"bun"` nor `"browser"` conditions are active (e.g. vanilla Node.js `require()`), the `exports.default` condition falls back to the Bun adapter entry point. The WASM path is never the fallback to avoid loading 1.5 MB of WASM in server-side contexts.
+
+## Implementation Notes
+
+`WasmDriverOptions` is imported from `../schemas/index.js` rather than from `wasm-driver.js` because the Zod schemas live in the shared schemas module — keeping the driver files free of Zod as a direct import. This pattern is consistent across all driver options types in this package.
+
+The WASM worker bundle (`wasm-worker.js`) is inlined as an asset URL by Vite at build time using `new URL("./wasm-worker.js", import.meta.url)`. The worker receives messages for `init`, `query`, `execute`, and `close`, and responds synchronously from SQLite's in-memory or OPFS-backed database.