@nativedesktop/data 0.1.0

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@nativedesktop/data",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://github.com/FormalSnake/NativeDesktop#readme",
+  "bugs": "https://github.com/FormalSnake/NativeDesktop/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FormalSnake/NativeDesktop.git",
+    "directory": "packages/data"
+  },
+  "publishConfig": {
+  "access": "public"
+},
+"files": ["src"],
+"main": "./src/index.ts",
+"types": "./src/index.ts",
+"exports": {
+  ".": "./src/index.ts",
+  "./react": "./src/react.ts"
+},
+"peerDependencies": {
+  "@nativedesktop/react": "^0.1.0"
+},
+"peerDependenciesMeta": {
+  "@nativedesktop/react": {
+  "optional": true
+}
+},
+"devDependencies": {
+  "drizzle-orm": "0.45.2",
+  "kysely": "0.29.2"
+}
+}

package/src/adapters.test.ts

@@ -0,0 +1,207 @@
+// Worker-backed Drizzle and Kysely, proven end-to-end.
+//
+// Neither ORM ships in @nativedesktop/data — both are devDependencies of this
+// package and appear ONLY as the userland adapter examples below. Each adapter
+// is a small function written against the package's public `SqliteExecutor`
+// contract (openDatabase() returns one that implements it); copy either into an
+// app, install the ORM as the app's own dependency, and you get a worker-backed
+// query builder whose heavy queries never touch React's commit loop.
+//
+// Run with: bun test packages/data/src/adapters.test.ts
+
+import { afterAll, expect, test } from "bun:test";
+import { eq, sql as dsql } from "drizzle-orm";
+import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
+import { drizzle } from "drizzle-orm/sqlite-proxy";
+import {
+  CompiledQuery,
+  type DatabaseConnection,
+  type Dialect,
+  type Driver,
+  type Generated,
+  Kysely,
+  type QueryResult,
+  SqliteAdapter,
+  SqliteIntrospector,
+  SqliteQueryCompiler,
+} from "kysely";
+import { openDatabase, type SqliteDatabase, type SqliteExecutor, type SqlParams } from "./index.ts";
+
+// ── Example adapter: Drizzle via drizzle-orm/sqlite-proxy ────────────────────
+// sqlite-proxy is Drizzle's official *async remote* driver: you hand it a
+// callback and it awaits your rows, so the whole builder returns Promises even
+// though Drizzle's bun-sqlite dialect is synchronous. That is what makes the
+// transparent async path feasible without forking Drizzle — the sync dialect
+// stays in the worker, only this proxy runs on the main thread. sqlite-proxy
+// reconstructs each result from a POSITIONAL value array, so we re-key each
+// object row bun:sqlite gives us into `Object.values` in projected-column order.
+// Caveat: a join selecting two same-named columns collapses in an object — such
+// selects need column aliases (or a `.values()`-shaped executor).
+function drizzleOverWorker<TSchema extends Record<string, unknown>>(exec: SqliteExecutor, schema: TSchema) {
+  return drizzle(
+    async (sql, params, method) => {
+      if (method === "run") {
+        await exec.mutate(sql, params);
+        return { rows: [] };
+      }
+      const rows = (await exec.query(sql, params)).map((row) => Object.values(row));
+      return { rows: method === "get" ? (rows[0] as unknown[]) : rows };
+    },
+    { schema },
+  );
+}
+
+// ── Example adapter: Kysely via a custom async Dialect ───────────────────────
+// Kysely's driver model is async-first: DatabaseConnection.executeQuery returns
+// a Promise of `{ rows }`, so it maps onto the worker with no shimming and no
+// row-shape conversion (Kysely keys rows by column name, which is exactly what
+// our `query` returns). We reuse Kysely's own SQLite compiler/adapter/
+// introspector and supply only the driver.
+class WorkerConnection implements DatabaseConnection {
+  constructor(private readonly exec: SqliteExecutor) {}
+
+  async executeQuery<R>(compiled: CompiledQuery): Promise<QueryResult<R>> {
+    const node = compiled.query as { kind: string; returning?: unknown };
+    const write =
+      node.kind === "InsertQueryNode" ||
+      node.kind === "UpdateQueryNode" ||
+      node.kind === "DeleteQueryNode" ||
+      node.kind === "MergeQueryNode";
+    if (write && node.returning == null) {
+      const r = await this.exec.mutate(compiled.sql, compiled.parameters as SqlParams);
+      return { rows: [], numAffectedRows: BigInt(r.changes), insertId: BigInt(r.lastInsertRowid) };
+    }
+    return { rows: await this.exec.query<R>(compiled.sql, compiled.parameters as SqlParams) };
+  }
+
+  async *streamQuery<R>(): AsyncIterableIterator<QueryResult<R>> {
+    throw new Error("streaming is not supported by the worker-backed SQLite driver");
+  }
+}
+
+function kyselyOverWorker<DB>(exec: SqliteExecutor): Kysely<DB> {
+  const connection = new WorkerConnection(exec);
+  const driver: Driver = {
+    async init() {},
+    async acquireConnection() {
+      return connection;
+    },
+    async beginTransaction(conn) {
+      await conn.executeQuery(CompiledQuery.raw("begin"));
+    },
+    async commitTransaction(conn) {
+      await conn.executeQuery(CompiledQuery.raw("commit"));
+    },
+    async rollbackTransaction(conn) {
+      await conn.executeQuery(CompiledQuery.raw("rollback"));
+    },
+    async releaseConnection() {},
+    async destroy() {},
+  };
+  const dialect: Dialect = {
+    createDriver: () => driver,
+    createQueryCompiler: () => new SqliteQueryCompiler(),
+    createAdapter: () => new SqliteAdapter(),
+    createIntrospector: (db) => new SqliteIntrospector(db),
+  };
+  return new Kysely<DB>({ dialect });
+}
+
+// ── Verification ─────────────────────────────────────────────────────────────
+
+const notes = sqliteTable("notes", {
+  id: integer("id").primaryKey({ autoIncrement: true }),
+  title: text("title").notNull(),
+  pinned: integer("pinned", { mode: "boolean" }).notNull(),
+});
+
+let db: SqliteDatabase;
+
+afterAll(async () => {
+  await db?.close();
+});
+
+test("Drizzle over the worker returns correctly-mapped rows via sqlite-proxy", async () => {
+  db = await openDatabase(":memory:");
+  await db.mutate(
+    "CREATE TABLE notes (id INTEGER PRIMARY KEY AUTOINCREMENT, title TEXT NOT NULL, pinned INTEGER NOT NULL)",
+  );
+  const d = drizzleOverWorker(db, { notes });
+
+  await d.insert(notes).values([
+    { title: "first", pinned: true },
+    { title: "second", pinned: false },
+  ]);
+
+  // Full-row select: proves positional mapping AND type decoding — `pinned` comes
+  // back as a real boolean (integer 1/0 in SQLite), which only works if the value
+  // array reached Drizzle's mapResultRow in the right column order.
+  const rows = await d.select().from(notes).orderBy(notes.id);
+  expect(rows).toEqual([
+    { id: 1, title: "first", pinned: true },
+    { id: 2, title: "second", pinned: false },
+  ]);
+
+  // Projected single-row select: exercises the `get` path and bound params.
+  const one = await d.select({ title: notes.title }).from(notes).where(eq(notes.id, 2)).get();
+  expect(one).toEqual({ title: "second" });
+});
+
+test("Kysely over the worker returns correctly-mapped rows via a custom async dialect", async () => {
+  interface KDB {
+    notes: { id: Generated<number>; title: string; pinned: number };
+  }
+  const k = kyselyOverWorker<KDB>(db);
+
+  const inserted = await k
+    .insertInto("notes")
+    .values({ title: "third", pinned: 1 })
+    .executeTakeFirstOrThrow();
+  expect(inserted.numInsertedOrUpdatedRows).toBe(1n); // sourced from our numAffectedRows
+  expect(inserted.insertId).toBe(3n); // sourced from lastInsertRowid
+
+  const rows = await k.selectFrom("notes").select(["title", "pinned"]).orderBy("id").execute();
+  expect(rows).toEqual([
+    { title: "first", pinned: 1 },
+    { title: "second", pinned: 0 },
+    { title: "third", pinned: 1 },
+  ]);
+});
+
+test("a heavy Drizzle query does not block the main thread", async () => {
+  const d = drizzleOverWorker(db, {});
+
+  let ticks = 0;
+  const heartbeat = setInterval(() => ticks++, 10);
+  const order: string[] = [];
+
+  const started = performance.now();
+  // Runs synchronously inside the worker (Drizzle's dialect is sync); the main
+  // thread only awaits the postMessage reply, so it must stay responsive.
+  const heavy = d
+    .all<[number]>(
+      dsql`WITH RECURSIVE c(n) AS (SELECT 1 UNION ALL SELECT n + 1 FROM c WHERE n < 3000000) SELECT count(*) AS c FROM c`,
+    )
+    .then((result) => {
+      order.push("drizzle-query");
+      return Number(result[0]?.[0]);
+    });
+
+  const independent = new Promise<void>((resolve) => setTimeout(resolve, 50)).then(() => {
+    order.push("independent-timer");
+  });
+
+  const [count] = await Promise.all([heavy, independent]);
+  clearInterval(heartbeat);
+  const elapsed = performance.now() - started;
+
+  console.log(
+    `heavy Drizzle query returned count=${count} after ${elapsed.toFixed(0)}ms; ` +
+      `main thread ticked ${ticks} times and the 50ms timer resolved first (order: ${order.join(" -> ")})`,
+  );
+
+  expect(count).toBe(3000000);
+  expect(elapsed).toBeGreaterThan(100); // the query really was slow
+  expect(order[0]).toBe("independent-timer"); // timer beat the ORM query -> not blocked
+  expect(ticks).toBeGreaterThan(3); // heartbeat kept advancing during the query
+});

package/src/client.ts

@@ -0,0 +1,140 @@
+// Main-thread client for the worker-backed SQLite connection. Nothing here
+// touches `bun:sqlite`; every call posts a message to sqlite.worker.ts and
+// returns a Promise resolved when the worker replies, so the Bun main thread
+// (which also runs React's commit loop) never blocks on a query.
+
+import type {
+  OpenOptions,
+  RunResult,
+  SerializedError,
+  SqlParams,
+  TxStep,
+  WorkerRequest,
+  WorkerResponse,
+} from "./protocol.ts";
+
+interface PendingCall {
+  resolve: (value: unknown) => void;
+  reject: (reason: Error) => void;
+}
+
+// A plain `Omit<WorkerRequest, "id">` collapses the discriminated union to its
+// shared `kind` key; distributing over the union keeps each variant's fields.
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+type RequestBody = DistributiveOmit<WorkerRequest, "id">;
+
+function rebuildError(error: SerializedError): Error {
+  const err = new Error(error.message);
+  err.name = error.name;
+  if (error.code !== undefined) (err as { code?: string }).code = error.code;
+  return err;
+}
+
+/**
+ * The async execution contract every call in this package ultimately speaks:
+ * `sql` + structured-clone-safe `params` in, a Promise of results out, with the
+ * synchronous `bun:sqlite` work happening in the worker. `SqliteDatabase`
+ * implements it; `openDatabase()` hands you one.
+ *
+ * This is the stable extension seam for query builders / ORMs. An adapter is a
+ * userland function that takes a `SqliteExecutor` and drives its own tool
+ * against these three methods — so the framework never depends on any ORM, and
+ * the app owns the ORM (its dependency, its version). Two example adapters,
+ * `drizzle-orm/sqlite-proxy` and a custom Kysely `Dialect`, are proven in
+ * `src/adapters.test.ts`; each is <20 lines against this interface.
+ */
+export interface SqliteExecutor {
+  /** Run a read query. Returns every row as a plain object keyed by column name. */
+  query<Row = Record<string, unknown>>(sql: string, params?: SqlParams): Promise<Row[]>;
+  /** Run an INSERT/UPDATE/DELETE (or any exec). Returns the affected-row count and last insert rowid. */
+  mutate(sql: string, params?: SqlParams): Promise<RunResult>;
+  /** Run a batch of statements atomically (BEGIN/COMMIT, rolled back if any step throws). */
+  transaction(steps: readonly TxStep[]): Promise<RunResult[]>;
+}
+
+export class SqliteDatabase implements SqliteExecutor {
+  readonly #worker: Worker;
+  #seq = 0;
+  #closed = false;
+  readonly #pending = new Map<number, PendingCall>();
+
+  private constructor(worker: Worker) {
+    this.#worker = worker;
+    worker.addEventListener("message", (event: MessageEvent<WorkerResponse>) => this.#onMessage(event.data));
+    // A worker-level error (e.g. the worker module failing to load) can never
+    // be tied to one request, so fail every in-flight call rather than hang.
+    worker.addEventListener("error", (event: ErrorEvent) =>
+      this.#failAll(new Error(`sqlite worker error: ${event.message}`)),
+    );
+  }
+
+  static async open(filename: string, options?: OpenOptions): Promise<SqliteDatabase> {
+    const worker = new Worker(new URL("./sqlite.worker.ts", import.meta.url).href, { type: "module" });
+    const db = new SqliteDatabase(worker);
+    try {
+      await db.#send({ kind: "open", filename, options });
+    } catch (err) {
+      worker.terminate();
+      throw err;
+    }
+    return db;
+  }
+
+  /** Run a read query. Returns every row as a plain object. */
+  query<Row = Record<string, unknown>>(sql: string, params?: SqlParams): Promise<Row[]> {
+    return this.#send<Row[]>({ kind: "query", sql, params });
+  }
+
+  /** Run an INSERT/UPDATE/DELETE (or any exec). Returns the affected-row count and last insert rowid. */
+  mutate(sql: string, params?: SqlParams): Promise<RunResult> {
+    return this.#send<RunResult>({ kind: "mutate", sql, params });
+  }
+
+  /** Run a batch of statements atomically (BEGIN/COMMIT, rolled back if any step throws). */
+  transaction(steps: readonly TxStep[]): Promise<RunResult[]> {
+    return this.#send<RunResult[]>({ kind: "transaction", steps });
+  }
+
+  /** Close the underlying database and terminate the worker. Idempotent. */
+  async close(): Promise<void> {
+    if (this.#closed) return;
+    const closed = this.#send({ kind: "close" }); // send while still open
+    this.#closed = true; // then reject any further calls
+    try {
+      await closed;
+    } finally {
+      this.#worker.terminate();
+      this.#failAll(new Error("database is closed"));
+    }
+  }
+
+  #send<T>(req: RequestBody): Promise<T> {
+    if (this.#closed) return Promise.reject(new Error("database is closed"));
+    const id = ++this.#seq;
+    return new Promise<T>((resolve, reject) => {
+      this.#pending.set(id, { resolve: resolve as (value: unknown) => void, reject });
+      this.#worker.postMessage({ ...req, id } as WorkerRequest);
+    });
+  }
+
+  #onMessage(res: WorkerResponse): void {
+    const call = this.#pending.get(res.id);
+    if (!call) return;
+    this.#pending.delete(res.id);
+    if (res.ok) call.resolve(res.result);
+    else call.reject(rebuildError(res.error));
+  }
+
+  #failAll(err: Error): void {
+    for (const call of this.#pending.values()) call.reject(err);
+    this.#pending.clear();
+  }
+}
+
+/**
+ * Open a worker-backed SQLite database. `filename` is caller-provided — pass
+ * `":memory:"`, an absolute path, or e.g. `` `${appDataDir()}/app.sqlite` ``.
+ */
+export function openDatabase(filename: string, options?: OpenOptions): Promise<SqliteDatabase> {
+  return SqliteDatabase.open(filename, options);
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+// @nativedesktop/data — a worker-backed, Promise-based SQLite data layer.
+// The connection lives in a Bun Worker (sqlite.worker.ts) so heavy queries run
+// off the main thread and never stall React's commit loop.
+//
+// The optional `useQuery` React hook lives at "@nativedesktop/data/react" so
+// this core entry stays free of any React dependency.
+
+export { openDatabase, SqliteDatabase } from "./client.ts";
+export type { SqliteExecutor } from "./client.ts";
+export type { OpenOptions, RunResult, SqlParams, SqlValue, TxStep } from "./protocol.ts";

package/src/protocol.ts

@@ -0,0 +1,48 @@
+// Wire types shared by the main-thread client (client.ts) and the SQLite
+// worker (sqlite.worker.ts). Every value here crosses a `postMessage`
+// boundary, so it must be structured-clone-safe: only SQLite-representable
+// scalars, no functions, no class instances. That constraint is why a
+// transaction is a *list of statements* (TxStep[]) and not a callback — a
+// closure can't be cloned to the worker.
+
+/** A single bindable SQLite value. `bigint`/`Uint8Array` clone fine over postMessage. */
+export type SqlValue = string | number | bigint | boolean | null | Uint8Array;
+
+/** Positional bindings (`?`, `?1`) or named bindings (`$id`, `:id`, `@id`). */
+export type SqlParams = readonly SqlValue[] | Readonly<Record<string, SqlValue>>;
+
+/** Result of a mutation, mirroring bun:sqlite's `Statement.run()` return. */
+export interface RunResult {
+  changes: number;
+  lastInsertRowid: number | bigint;
+}
+
+/** One statement in an atomic transaction batch. */
+export interface TxStep {
+  sql: string;
+  params?: SqlParams;
+}
+
+/** Passed straight through to `new Database(filename, options)` in the worker. */
+export interface OpenOptions {
+  readonly?: boolean;
+  create?: boolean;
+  readwrite?: boolean;
+}
+
+export type WorkerRequest =
+  | { id: number; kind: "open"; filename: string; options?: OpenOptions }
+  | { id: number; kind: "query"; sql: string; params?: SqlParams }
+  | { id: number; kind: "mutate"; sql: string; params?: SqlParams }
+  | { id: number; kind: "transaction"; steps: readonly TxStep[] }
+  | { id: number; kind: "close" };
+
+export interface SerializedError {
+  message: string;
+  name: string;
+  code?: string;
+}
+
+export type WorkerResponse =
+  | { id: number; ok: true; result: unknown }
+  | { id: number; ok: false; error: SerializedError };

package/src/react.ts

@@ -0,0 +1,50 @@
+// Optional React binding for @nativedesktop/data. Import from
+// "@nativedesktop/data/react". Kept separate from the core so apps that only
+// want the async client never pull in React.
+
+import { useEffect, useState } from "@nativedesktop/react";
+import type { SqliteDatabase } from "./client.ts";
+import type { SqlParams } from "./protocol.ts";
+
+export interface QueryState<Row> {
+  data: Row[] | undefined;
+  error: Error | undefined;
+  loading: boolean;
+}
+
+/**
+ * Run a read query and track its result as it resolves. Re-runs when `db`,
+ * `sql`, or `params` change; a superseded or unmounted query is ignored so
+ * late replies can't overwrite fresh state. Pass a nullish `db` (e.g. while it
+ * is still opening) to stay in the loading state without querying.
+ */
+export function useQuery<Row = Record<string, unknown>>(
+  db: SqliteDatabase | null | undefined,
+  sql: string,
+  params?: SqlParams,
+): QueryState<Row> {
+  const [state, setState] = useState<QueryState<Row>>({ data: undefined, error: undefined, loading: true });
+  const key = JSON.stringify([sql, params]);
+
+  // effect:audited — subscribes to an out-of-tree async source (the worker);
+  // re-keyed on sql/params so a changed query refetches with fresh bindings.
+  useEffect(() => {
+    if (!db) return;
+    let cancelled = false;
+    setState((prev) => (prev.loading ? prev : { ...prev, loading: true }));
+    db.query<Row>(sql, params).then(
+      (rows) => {
+        if (!cancelled) setState({ data: rows, error: undefined, loading: false });
+      },
+      (err: unknown) => {
+        if (!cancelled) setState({ data: undefined, error: err as Error, loading: false });
+      },
+    );
+    return () => {
+      cancelled = true;
+    };
+    // params is captured through `key`; listing it directly would re-run on every render.
+  }, [db, key]);
+
+  return state;
+}

package/src/sqlite.test.ts

@@ -0,0 +1,91 @@
+// Runtime verification for the worker-backed SQLite client. Run with:
+//   bun test packages/data/src/sqlite.test.ts
+//
+// Proves both halves of the promise: queries work end-to-end across the worker
+// boundary (round-trip, named params, transactions, error propagation), and a
+// deliberately slow query never blocks the Bun main thread that drives React.
+
+import { afterAll, expect, test } from "bun:test";
+import { openDatabase, type SqliteDatabase } from "./index.ts";
+
+let db: SqliteDatabase;
+
+afterAll(async () => {
+  await db?.close();
+});
+
+test("query + mutate round-trip through the worker", async () => {
+  db = await openDatabase(":memory:");
+  await db.mutate("CREATE TABLE notes (id INTEGER PRIMARY KEY, title TEXT, pinned INTEGER)");
+
+  const inserted = await db.mutate("INSERT INTO notes (title, pinned) VALUES (?, ?)", ["first", true]);
+  expect(inserted.changes).toBe(1);
+  expect(inserted.lastInsertRowid).toBe(1);
+
+  const rows = await db.query<{ id: number; title: string; pinned: number }>("SELECT * FROM notes ORDER BY id");
+  expect(rows).toEqual([{ id: 1, title: "first", pinned: 1 }]);
+
+  const named = await db.query("SELECT title FROM notes WHERE id = $id", { $id: 1 });
+  expect(named).toEqual([{ title: "first" }]);
+});
+
+test("transaction commits a batch atomically", async () => {
+  await db.mutate("DELETE FROM notes");
+  const results = await db.transaction([
+    { sql: "INSERT INTO notes (title, pinned) VALUES (?, 0)", params: ["a"] },
+    { sql: "INSERT INTO notes (title, pinned) VALUES (?, 1)", params: ["b"] },
+  ]);
+  expect(results.map((r) => r.changes)).toEqual([1, 1]);
+  const rows = await db.query<{ c: number }>("SELECT count(*) AS c FROM notes");
+  expect(rows[0]?.c).toBe(2);
+});
+
+test("a failing transaction rolls back and rejects", async () => {
+  await db.mutate("DELETE FROM notes");
+  await expect(
+    db.transaction([
+      { sql: "INSERT INTO notes (title, pinned) VALUES (?, 0)", params: ["kept?"] },
+      { sql: "INSERT INTO notes (nonexistent) VALUES (1)" }, // throws in the worker
+    ]),
+  ).rejects.toThrow(/nonexistent/);
+  const rows = await db.query<{ c: number }>("SELECT count(*) AS c FROM notes");
+  expect(rows[0]?.c).toBe(0); // the first insert was rolled back
+});
+
+test("a query error rejects with a usable message", async () => {
+  await expect(db.query("SELECT * FROM does_not_exist")).rejects.toThrow(/no such table: does_not_exist/);
+});
+
+test("a slow query does not block the main thread", async () => {
+  let ticks = 0;
+  const heartbeat = setInterval(() => ticks++, 10);
+  const order: string[] = [];
+
+  const started = performance.now();
+  const slowSql =
+    "WITH RECURSIVE c(n) AS (SELECT 1 UNION ALL SELECT n + 1 FROM c WHERE n < 3000000) SELECT count(*) AS c FROM c";
+  const slow = db.query<{ c: number }>(slowSql).then((rows) => {
+    order.push("slow-query");
+    return rows[0]?.c;
+  });
+
+  // An independent main-thread timer far shorter than the query. If the main
+  // thread were blocked by the query, this 50ms timer could not fire first.
+  const independent = new Promise<void>((resolve) => setTimeout(resolve, 50)).then(() => {
+    order.push("independent-timer");
+  });
+
+  const [count] = await Promise.all([slow, independent]);
+  clearInterval(heartbeat);
+  const elapsed = performance.now() - started;
+
+  console.log(
+    `slow query returned count=${count} after ${elapsed.toFixed(0)}ms; ` +
+      `main thread ticked ${ticks} times and the 50ms timer resolved first (order: ${order.join(" -> ")})`,
+  );
+
+  expect(count).toBe(3000000);
+  expect(elapsed).toBeGreaterThan(100); // the query really was slow
+  expect(order[0]).toBe("independent-timer"); // timer beat the query -> not blocked
+  expect(ticks).toBeGreaterThan(3); // heartbeat kept advancing during the query
+});

package/src/sqlite.worker.ts

@@ -0,0 +1,86 @@
+// The SQLite worker: the ONLY place `bun:sqlite` is opened. It runs on its own
+// thread, so every query here is off the Bun main thread that drives React's
+// commit loop — a slow `SELECT` blocks this worker, never the UI.
+//
+// Requests arrive in order on the worker's event loop and are answered by `id`,
+// so the client can have many in flight at once. The first request is always
+// `open`; queries the client sends afterwards are guaranteed to see an open DB
+// because openDatabase() awaits the open reply before handing back the client.
+
+import { Database, type Statement } from "bun:sqlite";
+import type { RunResult, SerializedError, SqlParams, TxStep, WorkerRequest, WorkerResponse } from "./protocol.ts";
+
+declare const self: Worker;
+
+let db: Database | null = null;
+
+function reply(res: WorkerResponse): void {
+  self.postMessage(res);
+}
+
+function serializeError(err: unknown): SerializedError {
+  if (err instanceof Error) {
+    const code = (err as { code?: unknown }).code;
+    return { message: err.message, name: err.name, code: typeof code === "string" ? code : undefined };
+  }
+  return { message: String(err), name: "Error" };
+}
+
+// bun:sqlite accepts positional bindings as a spread and named bindings as a
+// single object argument; normalize both shapes (and the no-params case) here.
+function all(stmt: Statement, params?: SqlParams): unknown[] {
+  if (params === undefined) return stmt.all() as unknown[];
+  return Array.isArray(params) ? (stmt.all(...params) as unknown[]) : (stmt.all(params) as unknown[]);
+}
+
+function run(stmt: Statement, params?: SqlParams): RunResult {
+  if (params === undefined) return stmt.run();
+  return Array.isArray(params) ? stmt.run(...params) : stmt.run(params);
+}
+
+function requireDb(): Database {
+  if (!db) throw new Error("database is not open");
+  return db;
+}
+
+self.onmessage = (event: MessageEvent<WorkerRequest>): void => {
+  const req = event.data;
+  try {
+    switch (req.kind) {
+      case "open": {
+        if (db) throw new Error("database is already open");
+        db = new Database(req.filename, req.options);
+        reply({ id: req.id, ok: true, result: null });
+        break;
+      }
+      case "query": {
+        const rows = all(requireDb().query(req.sql), req.params);
+        reply({ id: req.id, ok: true, result: rows });
+        break;
+      }
+      case "mutate": {
+        const result = run(requireDb().query(req.sql), req.params);
+        reply({ id: req.id, ok: true, result });
+        break;
+      }
+      case "transaction": {
+        const active = requireDb();
+        // db.transaction() wraps the batch in BEGIN/COMMIT and rolls back +
+        // rethrows if any step throws, giving us atomicity for free.
+        const batch = active.transaction((steps: readonly TxStep[]): RunResult[] =>
+          steps.map((step) => run(active.query(step.sql), step.params)),
+        );
+        reply({ id: req.id, ok: true, result: batch(req.steps) });
+        break;
+      }
+      case "close": {
+        db?.close();
+        db = null;
+        reply({ id: req.id, ok: true, result: null });
+        break;
+      }
+    }
+  } catch (err) {
+    reply({ id: req.id, ok: false, error: serializeError(err) });
+  }
+};