@dxos/sql-sqlite 0.0.0

package/LICENSE

@@ -0,0 +1,8 @@
+MIT License 
+Copyright (c) 2022 DXOS
+
+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,21 @@
+# @dxos/@dxos/sql-sqlite
+
+Sqlite client
+
+## Installation
+
+```bash
+pnpm i @dxos/@dxos/sql-sqlite
+```
+
+## DXOS Resources
+
+- [Website](https://dxos.org)
+- [Developer Documentation](https://docs.dxos.org)
+- Talk to us on [Discord](https://dxos.org/discord)
+
+## Contributions
+
+Your ideas, issues, and code are most welcome. Please take a look at our [community code of conduct](https://github.com/dxos/dxos/blob/main/CODE_OF_CONDUCT.md), the [issue guide](https://github.com/dxos/dxos/blob/main/CONTRIBUTING.md#submitting-issues), and the [PR contribution guide](https://github.com/dxos/dxos/blob/main/CONTRIBUTING.md#submitting-prs).
+
+License: [MIT](./LICENSE) Copyright 2022 © DXOS

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@dxos/sql-sqlite",
+  "version": "0.0.0",
+  "description": "Sqlite client",
+  "homepage": "https://dxos.org",
+  "bugs": "https://github.com/dxos/dxos/issues",
+  "license": "MIT",
+  "author": "info@dxos.org",
+  "sideEffects": true,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/types/src/index.d.ts",
+      "browser": "./dist/lib/browser/index.mjs",
+      "node": "./dist/lib/node-esm/index.mjs"
+    },
+    "./SqliteClient": {
+      "types": "./dist/types/src/SqliteClient.d.ts",
+      "browser": "./dist/lib/browser/SqliteClient.mjs",
+      "node": "./dist/lib/node-esm/SqliteClient.mjs"
+    },
+    "./OpfsWorker": {
+      "types": "./dist/types/src/OpfsWorker.d.ts",
+      "browser": "./dist/lib/browser/OpfsWorker.mjs",
+      "node": "./dist/lib/node-esm/OpfsWorker.mjs"
+    },
+    "./SqliteMigrator": {
+      "types": "./dist/types/src/SqliteMigrator.d.ts",
+      "browser": "./dist/lib/browser/SqliteMigrator.mjs",
+      "node": "./dist/lib/node-esm/SqliteMigrator.mjs"
+    },
+    "./platform": {
+      "types": "./dist/types/src/platform/browser.d.ts",
+      "browser": "./dist/lib/browser/platform/browser.mjs",
+      "bun": "./dist/lib/node-esm/platform/bun.mjs",
+      "node": "./dist/lib/node-esm/platform/node.mjs"
+    },
+    "./SqlExport": {
+      "types": "./dist/types/src/SqlExport.d.ts",
+      "browser": "./dist/lib/browser/SqlExport.mjs",
+      "node": "./dist/lib/node-esm/SqlExport.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@dxos/wa-sqlite": "^0.2.1",
+    "@effect/experimental": "0.57.11",
+    "@effect/platform": "0.93.6",
+    "@effect/sql": "0.48.6",
+    "@effect/sql-sqlite-bun": "0.49.0",
+    "@effect/sql-sqlite-node": "0.49.1",
+    "effect": "3.19.11"
+  },
+  "devDependencies": {
+    "@effect/sql-sqlite-wasm": "0.49.0",
+    "@effect/wa-sqlite": "^0.1.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "beast": {}
+}

package/src/OpfsWorker.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from '@effect/sql-sqlite-wasm/OpfsWorker';

package/src/SqlExport.ts

@@ -0,0 +1,13 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import type * as SqlError from '@effect/sql/SqlError';
+import * as Context from 'effect/Context';
+import type * as Effect from 'effect/Effect';
+
+export interface Service {
+  export: Effect.Effect<Uint8Array, SqlError.SqlError>;
+}
+
+export class SqlExport extends Context.Tag('@dxos/sql-sqlite/SqlExport')<SqlExport, Service>() {}

package/src/SqliteClient.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from '@effect/sql-sqlite-wasm/SqliteClient';

package/src/SqliteMigrator.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from '@effect/sql-sqlite-wasm/SqliteMigrator';

package/src/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from '@effect/sql-sqlite-wasm';
+export * as OpfsWorker from '@effect/sql-sqlite-wasm/OpfsWorker';
+export * as SqliteClient from '@effect/sql-sqlite-wasm/SqliteClient';
+export * as SqliteMigrator from '@effect/sql-sqlite-wasm/SqliteMigrator';

package/src/platform/browser.ts

@@ -0,0 +1,27 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import type * as SqlClient from '@effect/sql/SqlClient';
+import type * as SqlError from '@effect/sql/SqlError';
+import * as SqliteClient from '@effect/sql-sqlite-wasm/SqliteClient';
+import type * as ConfigError from 'effect/ConfigError';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+import * as SqlExport from '../SqlExport';
+
+const sqlExportBrowser: Layer.Layer<SqlExport.SqlExport, SqlError.SqlError, SqliteClient.SqliteClient> = Layer.effect(
+  SqlExport.SqlExport,
+  Effect.gen(function* () {
+    const sql = yield* SqliteClient.SqliteClient;
+    return {
+      export: sql.export,
+    } satisfies SqlExport.Service;
+  }),
+);
+
+export const layerMemory: Layer.Layer<
+  SqlClient.SqlClient | SqlExport.SqlExport,
+  ConfigError.ConfigError | SqlError.SqlError
+> = sqlExportBrowser.pipe(Layer.provideMerge(SqliteClient.layerMemory({})));

package/src/platform/bun.ts

@@ -0,0 +1,33 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import type * as SqlClient from '@effect/sql/SqlClient';
+import type * as SqlError from '@effect/sql/SqlError';
+import * as SqliteClient from '@effect/sql-sqlite-bun/SqliteClient';
+import type * as ConfigError from 'effect/ConfigError';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+import * as SqlExport from '../SqlExport';
+
+const sqlExportBun: Layer.Layer<SqlExport.SqlExport, SqlError.SqlError, SqliteClient.SqliteClient> = Layer.effect(
+  SqlExport.SqlExport,
+  Effect.gen(function* () {
+    const sql = yield* SqliteClient.SqliteClient;
+    return {
+      export: sql.export,
+    } satisfies SqlExport.Service;
+  }),
+);
+
+export const layerMemory: Layer.Layer<
+  SqlClient.SqlClient | SqliteClient.SqliteClient | SqlExport.SqlExport,
+  ConfigError.ConfigError | SqlError.SqlError
+> = sqlExportBun.pipe(
+  Layer.provideMerge(
+    SqliteClient.layer({
+      filename: ':memory:',
+    }),
+  ),
+);

package/src/platform/node.ts

@@ -0,0 +1,33 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import type * as SqlClient from '@effect/sql/SqlClient';
+import type * as SqlError from '@effect/sql/SqlError';
+import * as SqliteClient from '@effect/sql-sqlite-node/SqliteClient';
+import type * as ConfigError from 'effect/ConfigError';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+import * as SqlExport from '../SqlExport';
+
+const sqlExportNode: Layer.Layer<SqlExport.SqlExport, SqlError.SqlError, SqliteClient.SqliteClient> = Layer.effect(
+  SqlExport.SqlExport,
+  Effect.gen(function* () {
+    const sql = yield* SqliteClient.SqliteClient;
+    return {
+      export: sql.export,
+    } satisfies SqlExport.Service;
+  }),
+);
+
+export const layerMemory: Layer.Layer<
+  SqlClient.SqlClient | SqliteClient.SqliteClient,
+  ConfigError.ConfigError | SqlError.SqlError
+> = sqlExportNode.pipe(
+  Layer.provideMerge(
+    SqliteClient.layer({
+      filename: ':memory:',
+    }),
+  ),
+);

package/src/testing/opfs-worker.browser.test.ts

@@ -0,0 +1,34 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Reactivity from '@effect/experimental/Reactivity';
+import * as SqlClient from '@effect/sql/SqlClient';
+import { describe, expect, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+import * as SqliteClient from '../SqliteClient';
+
+describe.skip('opfs-worker browser test', () => {
+  it.effect(
+    'should run the opfs worker',
+    Effect.fnUntraced(function* () {
+      const clientLayer = SqliteClient.layer({
+        worker: Effect.sync(() => new Worker(new URL('./opfs-worker.ts', import.meta.url), { type: 'module' })),
+      });
+
+      yield* Effect.gen(function* () {
+        const client = yield* SqlClient.SqlClient;
+        yield* client`CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)`;
+        yield* client`INSERT INTO users (name) VALUES ('Alice')`;
+        yield* client`INSERT INTO users (name) VALUES ('Bob')`;
+        const results = yield* client`SELECT * FROM users`;
+
+        expect(results).toHaveLength(2);
+        expect(results[0].name).toBe('Alice');
+        expect(results[1].name).toBe('Bob');
+      }).pipe(Effect.provide(clientLayer.pipe(Layer.provideMerge(Reactivity.layer))));
+    }),
+  );
+});

package/src/testing/opfs-worker.ts

@@ -0,0 +1,13 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+/// <reference lib="webworker" />
+
+import * as Effect from 'effect/Effect';
+
+import * as OpfsWorker from '../OpfsWorker';
+
+const DB_NAME = 'DXOS';
+
+void Effect.runFork(OpfsWorker.run({ port: self, dbName: DB_NAME }));

package/src/testing/sqlite-effect-idb.browser.test.ts

@@ -0,0 +1,265 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Reactivity from '@effect/experimental/Reactivity';
+import * as SqlClient from '@effect/sql/SqlClient';
+import type * as SqlConnection from '@effect/sql/SqlConnection';
+import * as SqlError from '@effect/sql/SqlError';
+import * as Statement from '@effect/sql/Statement';
+import { describe, expect, it } from '@effect/vitest';
+import * as Chunk from 'effect/Chunk';
+import * as Effect from 'effect/Effect';
+import * as Function from 'effect/Function';
+import * as Layer from 'effect/Layer';
+import * as Scope from 'effect/Scope';
+import * as Stream from 'effect/Stream';
+
+// @ts-expect-error
+import { SQLITE_OPEN_CREATE, SQLITE_OPEN_READWRITE } from '@dxos/wa-sqlite';
+// @ts-expect-error
+import * as WaSqlite from '@dxos/wa-sqlite';
+// @ts-expect-error
+import SQLiteAsyncESMFactory from '@dxos/wa-sqlite/dist/wa-sqlite-async.mjs';
+// @ts-expect-error
+import { IDBBatchAtomicVFS } from '@dxos/wa-sqlite/src/examples/IDBBatchAtomicVFS.js';
+
+//
+// Copyright 2025 DXOS.org
+//
+
+const TEST_VFS_NAME = 'idbbatchvfs';
+
+// Resolve WASM URL explicitly for Vite compatibility.
+const wasmUrl = new URL('@dxos/wa-sqlite/dist/wa-sqlite-async.wasm', import.meta.url).href;
+
+const ATTR_DB_SYSTEM_NAME = 'db.system.name';
+
+export interface SqliteClientIDBConfig {
+  readonly dbName: string;
+  readonly installReactivityHooks?: boolean;
+  readonly spanAttributes?: Record<string, unknown>;
+  readonly transformResultNames?: (str: string) => string;
+  readonly transformQueryNames?: (str: string) => string;
+}
+
+/**
+ * @category type ids
+ * @since 1.0.0
+ */
+export const TypeId: unique symbol = Symbol.for('@effect/sql-sqlite-wasm/SqliteClient');
+
+/**
+ * @category type ids
+ * @since 1.0.0
+ */
+export type TypeId = typeof TypeId;
+
+/**
+ * @category constructor
+ * @since 1.0.0
+ */
+export const makeIdb = (
+  options: SqliteClientIDBConfig,
+): Effect.Effect<SqlClient.SqlClient, SqlError.SqlError, Scope.Scope | Reactivity.Reactivity> =>
+  Effect.gen(function* () {
+    const reactivity = yield* Reactivity.Reactivity;
+    const compiler = Statement.makeCompilerSqlite(options.transformQueryNames);
+    const transformRows = options.transformResultNames
+      ? Statement.defaultTransforms(options.transformResultNames).array
+      : undefined;
+
+    const makeConnection = Effect.gen(function* () {
+      const factory = yield* Effect.promise(() =>
+        SQLiteAsyncESMFactory({
+          locateFile: (path: string) => (path.endsWith('.wasm') ? wasmUrl : path),
+        }),
+      );
+      const sqlite3 = WaSqlite.Factory(factory);
+
+      const vfs = yield* Effect.promise(() => IDBBatchAtomicVFS.create(TEST_VFS_NAME, factory));
+      console.log({ reg: sqlite3.vfs_register(vfs as any, false) });
+      // }
+      const db = yield* Effect.acquireRelease(
+        Effect.try({
+          try: () => sqlite3.open_v2(options.dbName, SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE, TEST_VFS_NAME),
+          catch: (cause) => new SqlError.SqlError({ cause, message: 'Failed to open database' }),
+        }),
+        (db) => Effect.sync(() => sqlite3.close(db)),
+      );
+
+      if (options.installReactivityHooks) {
+        sqlite3.update_hook(db, (_op: any, _db: any, table: any, rowid: any) => {
+          if (!table) return;
+          const id = String(Number(rowid));
+          reactivity.unsafeInvalidate({ [table]: [id] });
+        });
+      }
+
+      const run = (sql: string, params: ReadonlyArray<unknown> = [], rowMode: 'object' | 'array' = 'object') =>
+        Effect.try({
+          try: () => {
+            const results: Array<any> = [];
+            for (const stmt of sqlite3.statements(db, sql)) {
+              let columns: Array<string> | undefined;
+              sqlite3.bind_collection(stmt, params as any);
+              while (sqlite3.step(stmt) === WaSqlite.SQLITE_ROW) {
+                columns = columns ?? sqlite3.column_names(stmt);
+                const row = sqlite3.row(stmt);
+                if (rowMode === 'object') {
+                  const obj: Record<string, any> = {};
+                  for (let i = 0; i < columns!.length; i++) {
+                    obj[columns![i]] = row[i];
+                  }
+                  results.push(obj);
+                } else {
+                  results.push(row);
+                }
+              }
+            }
+            return results;
+          },
+          catch: (cause) => new SqlError.SqlError({ cause, message: 'Failed to execute statement' }),
+        });
+
+      return Function.identity<SqlConnection.Connection>({
+        execute: (sql, params, transformRows) =>
+          transformRows ? Effect.map(run(sql, params), transformRows) : run(sql, params),
+        executeRaw: (sql, params) => run(sql, params),
+        executeValues: (sql, params) => run(sql, params, 'array'),
+        executeUnprepared(sql, params, transformRows) {
+          return this.execute(sql, params, transformRows);
+        },
+        executeStream: (sql, params, transformRows) => {
+          function* stream() {
+            for (const stmt of sqlite3.statements(db, sql)) {
+              let columns: Array<string> | undefined;
+              sqlite3.bind_collection(stmt, params as any);
+              while (sqlite3.step(stmt) === WaSqlite.SQLITE_ROW) {
+                columns = columns ?? sqlite3.column_names(stmt);
+                const row = sqlite3.row(stmt);
+                const obj: Record<string, any> = {};
+                for (let i = 0; i < columns!.length; i++) {
+                  obj[columns![i]] = row[i];
+                }
+                yield obj;
+              }
+            }
+          }
+          return Stream.suspend(() => Stream.fromIteratorSucceed(stream()[Symbol.iterator]())).pipe(
+            transformRows
+              ? Stream.mapChunks((chunk) => Chunk.unsafeFromArray(transformRows(Chunk.toReadonlyArray(chunk))))
+              : Function.identity,
+            Stream.mapError((cause) => new SqlError.SqlError({ cause, message: 'Failed to execute statement' })),
+          );
+        },
+        //  export: Effect.try({
+        //   try: () => sqlite3.serialize(db, 'main'),
+        //   catch: (cause) => new SqlError({ cause, message: 'Failed to export database' }),
+        // }),
+        // import: (data) =>
+        //   Effect.try({
+        //     try: () => sqlite3.deserialize(db, 'main', data, data.length, data.length, 1 | 2),
+        //     catch: (cause) => new SqlError({ cause, message: 'Failed to import database' }),
+        //   }),
+      });
+    });
+
+    const semaphore = yield* Effect.makeSemaphore(1);
+    const connection = yield* makeConnection;
+
+    const acquirer = semaphore.withPermits(1)(Effect.succeed(connection));
+    const transactionAcquirer = Effect.uninterruptibleMask((restore) =>
+      Effect.as(
+        Effect.zipRight(
+          restore(semaphore.take(1)),
+          Effect.tap(Effect.scope, (scope) => Scope.addFinalizer(scope, semaphore.release(1))),
+        ),
+        connection,
+      ),
+    );
+
+    return Object.assign(
+      (yield* SqlClient.make({
+        acquirer,
+        compiler,
+        transactionAcquirer,
+        spanAttributes: [
+          ...(options.spanAttributes ? Object.entries(options.spanAttributes) : []),
+          [ATTR_DB_SYSTEM_NAME, 'sqlite'],
+        ],
+        transformRows,
+      })) as SqlClient.SqlClient,
+      {
+        [TypeId]: TypeId as TypeId,
+        config: options,
+        // export: semaphore.withPermits(1)(connection.export),
+        // import: (data: Uint8Array) => semaphore.withPermits(1)(connection.import(data)),
+      },
+    );
+  });
+
+const TestLayer = Layer.scoped(
+  SqlClient.SqlClient,
+  makeIdb({
+    dbName: 'testing',
+  }),
+).pipe(Layer.provideMerge(Reactivity.layer));
+
+// Doesn't work yet.
+describe.skip('effect SQLite with IDBBatchAtomicVFS', () => {
+  it.effect(
+    'basic CRUD operations',
+    Effect.fnUntraced(function* () {
+      const sql = yield* SqlClient.SqlClient;
+
+      // Create table.
+      yield* sql`
+      CREATE TABLE IF NOT EXISTS users (
+        id INTEGER PRIMARY KEY,
+        name TEXT NOT NULL,
+        email TEXT
+      )
+    `;
+
+      // Insert data.
+      yield* sql`
+      INSERT INTO users (name, email) VALUES ('Alice', 'alice@example.com');
+      INSERT INTO users (name, email) VALUES ('Bob', 'bob@example.com');
+    `;
+
+      // Select data.
+      const results = yield* sql`SELECT * FROM users ORDER BY id`;
+
+      expect(results).toHaveLength(2);
+      expect(results[0].name).toBe('Alice');
+      expect(results[1].name).toBe('Bob');
+
+      // // Update data.
+      // await sqlite3.exec(db, `UPDATE users SET email = 'alice.updated@example.com' WHERE name = 'Alice'`);
+
+      // // Verify update.
+      // const updatedResults: Array<{ email: string }> = [];
+      // await sqlite3.exec(db, `SELECT email FROM users WHERE name = 'Alice'`, (row: any[]) => {
+      //   updatedResults.push({ email: row[0] });
+      // });
+      // expect(updatedResults[0].email).toBe('alice.updated@example.com');
+
+      // // Delete data.
+      // await sqlite3.exec(db, `DELETE FROM users WHERE name = 'Bob'`);
+
+      // // Verify deletion.
+      // const remainingResults: Array<{ name: string }> = [];
+      // await sqlite3.exec(db, 'SELECT name FROM users', (row: any[]) => {
+      //   remainingResults.push({ name: row[0] });
+      // });
+      // expect(remainingResults).toHaveLength(1);
+      // expect(remainingResults[0].name).toBe('Alice');
+
+      // // Close database.
+      // await sqlite3.close(db);
+
+      // await sleep(10000000);
+    }, Effect.provide(TestLayer)),
+  );
+});

package/src/testing/sqlite-idb.browser.test.ts

@@ -0,0 +1,113 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { afterEach, describe, expect, test } from 'vitest';
+
+// @ts-expect-error
+import * as WaSqlite from '@dxos/wa-sqlite';
+// @ts-expect-error
+import { SQLITE_ROW } from '@dxos/wa-sqlite';
+// @ts-expect-error - No type declarations for this module.
+import SQLiteAsyncESMFactory from '@dxos/wa-sqlite/dist/wa-sqlite-async.mjs';
+// @ts-expect-error - No type declarations for this module.
+import { IDBBatchAtomicVFS } from '@dxos/wa-sqlite/src/examples/IDBBatchAtomicVFS.js';
+
+const TEST_VFS_NAME = 'test-idb-vfs';
+
+// Resolve WASM URL explicitly for Vite compatibility.
+const wasmUrl = new URL('@dxos/wa-sqlite/dist/wa-sqlite-async.wasm', import.meta.url).href;
+
+/**
+ * Delete IndexedDB database.
+ */
+const deleteDatabase = (name: string): Promise<void> =>
+  new Promise((resolve, reject) => {
+    const request = indexedDB.deleteDatabase(name);
+    request.onsuccess = () => resolve();
+    request.onerror = () => reject(request.error);
+  });
+
+// Doesn't work yet.
+describe.skip('wa-sqlite with IDBBatchAtomicVFS', () => {
+  let sqlite3: ReturnType<typeof WaSqlite.Factory>;
+  let vfs: any;
+  let db: number;
+
+  afterEach(async () => {
+    // Close database.
+    if (db && sqlite3) {
+      await sqlite3.close(db);
+      db = 0;
+    }
+    // Note: Skip vfs.close() - it fails with "Cannot read properties of undefined (reading 'flags')".
+    // Just clean up IndexedDB.
+    await deleteDatabase(TEST_VFS_NAME).catch(() => {});
+  });
+
+  test('basic CRUD operations', async () => {
+    // Initialize async WASM module.
+    console.log(1);
+    const module = await SQLiteAsyncESMFactory({
+      locateFile: (path: string) => (path.endsWith('.wasm') ? wasmUrl : path),
+    });
+    sqlite3 = WaSqlite.Factory(module);
+    console.log(2);
+    // Create and register IDBBatchAtomicVFS.
+    vfs = IDBBatchAtomicVFS.create('demo', module, { lockPolicy: 'shared+hint' });
+    console.log(3);
+    console.log('vfs methods:', Object.keys(vfs));
+    console.log('vfs.name:', vfs.name);
+    const reg = sqlite3.vfs_register(vfs, true);
+    console.log(4, { reg });
+
+    try {
+      // Open database.
+      db = await sqlite3.open_v2('foo');
+      console.log(5, { db });
+    } catch (error) {
+      console.error(error);
+      throw error;
+    }
+
+    console.log(6, '___START___');
+    // Create table.
+    await sqlite3.exec(
+      db,
+      `
+      CREATE TABLE IF NOT EXISTS users (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        name TEXT NOT NULL,
+        email TEXT
+      )
+    `,
+    );
+    console.log(7, '___CREATE TABLE___');
+    // Insert data.
+    await sqlite3.exec(db, `INSERT INTO users (name, email) VALUES ('Alice', 'alice@example.com')`);
+    await sqlite3.exec(db, `INSERT INTO users (name, email) VALUES ('Bob', 'bob@example.com')`);
+    console.log(8, '___INSERT DATA___');
+    // Select data using statements API.
+    const results: Array<{ id: number; name: string; email: string }> = [];
+    for await (const stmt of sqlite3.statements(db, 'SELECT * FROM users ORDER BY id')) {
+      let columns: string[] | undefined;
+      while ((await sqlite3.step(stmt)) === SQLITE_ROW) {
+        columns = columns ?? sqlite3.column_names(stmt);
+        const row = sqlite3.row(stmt);
+        results.push({
+          id: row[0] as number,
+          name: row[1] as string,
+          email: row[2] as string,
+        });
+      }
+    }
+    console.log(9, '___SELECT DATA___');
+    console.log(10, { results });
+    console.log(11, '___EXPECTATIONS___');
+    expect(results).toHaveLength(2);
+    console.log(12, '___EXPECTATIONS___');
+    expect(results[0].name).toBe('Alice');
+    expect(results[0].email).toBe('alice@example.com');
+    expect(results[1].name).toBe('Bob');
+  });
+});

package/src/testing/sqlite-memory.browser.test.ts

@@ -0,0 +1,78 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
+
+// @ts-expect-error
+import * as WaSqlite from '@dxos/wa-sqlite';
+// @ts-expect-error
+import { SQLITE_OPEN_CREATE, SQLITE_OPEN_READWRITE } from '@dxos/wa-sqlite';
+// @ts-expect-error
+import { SQLITE_ROW } from '@dxos/wa-sqlite';
+// @ts-expect-error
+import SQLiteAsyncESMFactory from '@dxos/wa-sqlite/dist/wa-sqlite-async.mjs';
+
+// Resolve WASM URL explicitly for Vite compatibility.
+const wasmUrl = new URL('@dxos/wa-sqlite/dist/wa-sqlite-async.wasm', import.meta.url).href;
+
+describe('wa-sqlite in-memory database', () => {
+  let sqlite3: ReturnType<typeof WaSqlite.Factory>;
+  let db: number;
+
+  beforeEach(async () => {
+    // Initialize async WASM module.
+    const module = await SQLiteAsyncESMFactory({
+      locateFile: (path: string) => wasmUrl,
+    });
+    sqlite3 = WaSqlite.Factory(module);
+
+    // Open in-memory database (no VFS needed).
+    db = sqlite3.open_v2(':memory:', SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE);
+  });
+
+  afterEach(async () => {
+    if (db && sqlite3) {
+      sqlite3.close(db);
+      db = 0;
+    }
+  });
+
+  test('basic CRUD operations', async () => {
+    // Create table.
+    sqlite3.exec(
+      db,
+      `
+      CREATE TABLE users (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        name TEXT NOT NULL,
+        email TEXT
+      )
+    `,
+    );
+
+    // Insert data.
+    sqlite3.exec(db, `INSERT INTO users (name, email) VALUES ('Alice', 'alice@example.com')`);
+    sqlite3.exec(db, `INSERT INTO users (name, email) VALUES ('Bob', 'bob@example.com')`);
+
+    // Select data using statements API.
+    const results: Array<{ id: number; name: string; email: string }> = [];
+    for (const stmt of sqlite3.statements(db, 'SELECT * FROM users ORDER BY id')) {
+      let columns: string[] | undefined;
+      while (sqlite3.step(stmt) === SQLITE_ROW) {
+        columns = columns ?? sqlite3.column_names(stmt);
+        const row = sqlite3.row(stmt);
+        results.push({
+          id: row[0] as number,
+          name: row[1] as string,
+          email: row[2] as string,
+        });
+      }
+    }
+
+    expect(results).toHaveLength(2);
+    expect(results[0].name).toBe('Alice');
+    expect(results[0].email).toBe('alice@example.com');
+    expect(results[1].name).toBe('Bob');
+  });
+});