@semics-tech/mongolite 1.0.0 → 1.2.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 YOUR_NAME
+Copyright (c) 2025 Oliver Breeden
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -18,12 +18,13 @@ A MongoDB-like client backed by SQLite. Use a familiar MongoDB API with the simp
 - **MongoDB-compatible API** — `insertOne`, `findOne`, `updateOne`, `deleteOne`, `find`, `aggregate`, and more
 - **SQLite persistence** — single file, zero configuration, works offline
 - **Automatic `_id` generation** — UUID assigned on insert if not provided
-- **WAL mode** — Write-Ahead Logging for better concurrent read access
+- **WAL mode** — Write-Ahead Logging for better concurrent read access, on by default
+- **Shared connections** — opt into one pooled connection per file per process
 - **Rich query operators** — `$eq`, `$gt`, `$in`, `$and`, `$or`, `$elemMatch`, `$regex`, and more
 - **Update operators** — `$set`, `$inc`, `$push`, `$pull`, `$addToSet`, `$mul`, and more
 - **Indexing** — create, list, and drop indexes including unique and compound indexes
 - **Change streams** — real-time change tracking via `collection.watch()`
-- **JSON safety** — validates documents before insert and recovers from corrupted data
+- **JSON safety** — validates documents before insert, and a corrupted row can't break queries for the rest of the collection
 - **TypeScript** — fully typed with strict mode
 
 ## Installation
@@ -32,6 +33,13 @@ A MongoDB-like client backed by SQLite. Use a familiar MongoDB API with the simp
 npm install @semics-tech/mongolite
 ```
 
+Requires **Node.js 22.5.0+** by default — the main entry point is backed by
+Node's built-in `node:sqlite` module, so there's no native addon to install or
+build. On an older Node.js runtime, use the `better-sqlite3`-backed adapter
+instead; see [Native `node:sqlite` vs. `better-sqlite3`](#native-nodesqlite-vs-better-sqlite3) below.
+
+Ships both ESM (`import`) and CommonJS (`require`) builds — use whichever your project already uses.
+
 ## Quick Start
 
 ```typescript
@@ -99,6 +107,43 @@ await users.insertOne({ name: 'Alice', age: 30 });
 await client.close();
 ```
 
+### Connection options
+
+```typescript
+const client = new MongoLite({
+  filePath: './myapp.sqlite',
+  WAL: true,          // Write-Ahead Logging. Default: true
+  busyTimeout: 5000,  // ms to wait for a lock before SQLITE_BUSY. Default: 5000
+  shared: true,       // reuse one connection per file in this process. Default: false
+  readOnly: false,
+  verbose: false,
+});
+```
+
+#### Sharing one connection across a process
+
+Applications often end up with several clients pointing at the same database file
+— a module-level client, a background job, a request handler — each opening its
+own connection, and each then hand-rolling an instance cache to avoid the
+resulting lock contention. `shared: true` moves that into the library:
+
+```typescript
+// Both resolve to the same file, so they share a single SQLite connection.
+const a = new MongoLite({ filePath: './app.sqlite', shared: true });
+const b = new MongoLite({ filePath: './app.sqlite', shared: true });
+
+await a.close(); // b keeps working — the handle is reference counted
+await b.close(); // last holder out actually closes it
+```
+
+Connections are only shared when the resolved path *and* every setting that
+changes the handle's behaviour match. `:memory:` databases are never shared,
+since two `:memory:` opens are two unrelated databases.
+
+This dedupes connections **within a process only**. Separate processes each get
+their own, so cross-process contention is handled by WAL mode and `busyTimeout`
+instead.
+
 ### In-memory (tests / ephemeral)
 
 ```typescript
@@ -112,6 +157,37 @@ await users.insertOne({ name: 'Alice', age: 30 });
 await client.close();
 ```
 
+### `better-sqlite3` (optional, for Node.js <22.5 or Bun)
+
+The default backend above uses Node's built-in `node:sqlite` module, which
+requires Node.js 22.5.0+. If you're on an older Node.js runtime, or you
+simply prefer the more battle-tested native addon, import from the
+`@semics-tech/mongolite/better-sqlite3` entry point instead. `better-sqlite3` is an
+**optional dependency** — install it yourself if it wasn't already pulled in:
+
+```bash
+npm install better-sqlite3
+```
+
+```typescript
+import { MongoLite } from '@semics-tech/mongolite/better-sqlite3';
+
+const client = new MongoLite('./myapp.sqlite');
+await client.connect();
+const users = client.collection('users');
+await users.insertOne({ name: 'Alice', age: 30 });
+await client.close();
+```
+
+<a id="native-nodesqlite-vs-better-sqlite3"></a>
+> **Which one should I use?** `node:sqlite` (the default) is still marked
+> experimental upstream but requires no native build step, which is why it's
+> the default here. `better-sqlite3` is the older, more battle-tested native
+> addon — reach for it if you're stuck on Node.js <22.5, targeting Bun without
+> a `node:sqlite` polyfill, or want to avoid depending on an experimental
+> Node.js API in production. Both implement the same `IDatabaseAdapter`
+> interface, so switching between them is a one-line import change.
+
 ### Browser (via sql.js)
 
 Requires [sql.js](https://www.npmjs.com/package/sql.js) (`npm install sql.js`).

package/dist/adapters/node-sqlite.d.ts

@@ -0,0 +1,65 @@
+import { DatabaseSync } from 'node:sqlite';
+import type { IDatabaseAdapter, MongoLiteOptions } from '../db.js';
+/** Exposed for tests and diagnostics. */
+export declare function sharedConnectionCount(): number;
+/**
+ * Database adapter backed by Node.js's built-in `node:sqlite` module — no native
+ * addon, no prebuilt binary, no `node-gyp`. Requires Node.js 22.5.0+ (the module
+ * is marked experimental by Node.js until it graduates to stable).
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { MongoLite, NodeSqliteAdapter } from '@semics-tech/mongolite';
+ *
+ * const client = new MongoLite(new NodeSqliteAdapter('./data.db'));
+ * await client.connect();
+ * const users = client.collection('users');
+ * await users.insertOne({ name: 'Alice', age: 30 });
+ * await client.close();
+ * ```
+ *
+ * ## Limitations
+ *
+ * - **Experimental.** `node:sqlite` is still marked experimental upstream and its
+ *   API may change between Node.js minor versions.
+ * - **Node.js 22.5.0+ only.** Importing this adapter on an older runtime (or on
+ *   Bun/Deno without a `node:sqlite` polyfill) throws at import time.
+ * - Rows are returned with a `null` prototype (per `node:sqlite`'s API). Plain
+ *   property access (`row.foo`) and `JSON.stringify`/`Object.keys` all work as
+ *   expected; `row.hasOwnProperty(...)` does not.
+ */
+export declare class NodeSqliteAdapter implements IDatabaseAdapter {
+    private db;
+    private readonly filePath;
+    private readonly verbose;
+    private readonly readOnly;
+    private readonly WAL;
+    private readonly busyTimeout;
+    private readonly shareKey;
+    private openPromise;
+    /**
+     * @param dbPathOrOptions Path to the SQLite database file (use `':memory:'`
+     * for an in-memory database), or an options object mirroring the built-in
+     * `better-sqlite3` adapter's `MongoLiteOptions`.
+     */
+    constructor(dbPathOrOptions: string | MongoLiteOptions);
+    /**
+     * Opens the database connection if it's not already open.
+     */
+    connect(): Promise<void>;
+    private ensureConnected;
+    run(sql: string, params?: unknown[]): Promise<{
+        lastID: number;
+        changes: number;
+    }>;
+    get<T>(sql: string, params?: unknown[]): Promise<T | undefined>;
+    all<T>(sql: string, params?: unknown[]): Promise<T[]>;
+    exec(sql: string): Promise<void>;
+    close(): Promise<void>;
+    /**
+     * Gets the underlying `node:sqlite` `DatabaseSync` instance.
+     * Useful for operations not covered by this wrapper.
+     */
+    getDbInstance(): Promise<DatabaseSync>;
+}

package/dist/adapters/node-sqlite.js

@@ -0,0 +1,241 @@
+import { DatabaseSync } from 'node:sqlite';
+import path from 'node:path';
+import { ConnectionRegistry, DEFAULT_BUSY_TIMEOUT_MS, buildConnectionKey, isShareablePath, } from '../utils/connection-registry.js';
+/** Shared `node:sqlite` handles for this process, keyed by connection identity. */
+const sharedConnections = new ConnectionRegistry();
+/** Exposed for tests and diagnostics. */
+export function sharedConnectionCount() {
+    return sharedConnections.size;
+}
+/**
+ * Database adapter backed by Node.js's built-in `node:sqlite` module — no native
+ * addon, no prebuilt binary, no `node-gyp`. Requires Node.js 22.5.0+ (the module
+ * is marked experimental by Node.js until it graduates to stable).
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { MongoLite, NodeSqliteAdapter } from '@semics-tech/mongolite';
+ *
+ * const client = new MongoLite(new NodeSqliteAdapter('./data.db'));
+ * await client.connect();
+ * const users = client.collection('users');
+ * await users.insertOne({ name: 'Alice', age: 30 });
+ * await client.close();
+ * ```
+ *
+ * ## Limitations
+ *
+ * - **Experimental.** `node:sqlite` is still marked experimental upstream and its
+ *   API may change between Node.js minor versions.
+ * - **Node.js 22.5.0+ only.** Importing this adapter on an older runtime (or on
+ *   Bun/Deno without a `node:sqlite` polyfill) throws at import time.
+ * - Rows are returned with a `null` prototype (per `node:sqlite`'s API). Plain
+ *   property access (`row.foo`) and `JSON.stringify`/`Object.keys` all work as
+ *   expected; `row.hasOwnProperty(...)` does not.
+ */
+export class NodeSqliteAdapter {
+    /**
+     * @param dbPathOrOptions Path to the SQLite database file (use `':memory:'`
+     * for an in-memory database), or an options object mirroring the built-in
+     * `better-sqlite3` adapter's `MongoLiteOptions`.
+     */
+    constructor(dbPathOrOptions) {
+        this.db = null;
+        this.openPromise = null;
+        let shared;
+        if (typeof dbPathOrOptions === 'string') {
+            this.filePath = dbPathOrOptions;
+            this.verbose = false;
+            this.readOnly = false;
+            this.WAL = true;
+            this.busyTimeout = DEFAULT_BUSY_TIMEOUT_MS;
+            shared = false;
+        }
+        else {
+            this.filePath = dbPathOrOptions.filePath;
+            this.verbose = dbPathOrOptions.verbose || false;
+            this.readOnly = dbPathOrOptions.readOnly || false;
+            this.WAL = dbPathOrOptions.WAL ?? true;
+            this.busyTimeout = dbPathOrOptions.busyTimeout ?? DEFAULT_BUSY_TIMEOUT_MS;
+            shared = dbPathOrOptions.shared ?? false;
+        }
+        this.shareKey =
+            shared && isShareablePath(this.filePath)
+                ? buildConnectionKey({
+                    backend: 'node:sqlite',
+                    filePath: path.resolve(this.filePath),
+                    readOnly: this.readOnly,
+                    WAL: this.WAL,
+                    busyTimeout: this.busyTimeout,
+                    verbose: this.verbose,
+                })
+                : null;
+    }
+    /**
+     * Opens the database connection if it's not already open.
+     */
+    async connect() {
+        if (this.db && this.openPromise) {
+            return this.openPromise;
+        }
+        if (this.db) {
+            return Promise.resolve();
+        }
+        this.openPromise = new Promise((resolve, reject) => {
+            try {
+                // Only runs on a genuinely new connection — when sharing, an existing
+                // handle already has its pragmas and UDFs applied.
+                const openConnection = () => {
+                    const db = new DatabaseSync(this.filePath, { readOnly: this.readOnly });
+                    if (this.WAL && !this.readOnly) {
+                        db.exec('PRAGMA journal_mode = WAL');
+                    }
+                    // Wait rather than immediately throwing SQLITE_BUSY when another
+                    // connection (often another process) holds a lock.
+                    if (this.busyTimeout > 0) {
+                        db.exec(`PRAGMA busy_timeout = ${this.busyTimeout}`);
+                    }
+                    // Register regexp UDF for $regex operator support.
+                    // WARNING: Patterns are compiled via JavaScript RegExp. User-supplied patterns that are
+                    // not validated for catastrophic backtracking (ReDoS) could block the event loop.
+                    // Avoid using untrusted/unvalidated patterns with $regex in security-sensitive contexts.
+                    db.function('regexp', { deterministic: true }, (pattern, value) => {
+                        if (typeof pattern !== 'string' || value === null || value === undefined)
+                            return 0;
+                        try {
+                            return new RegExp(pattern).test(String(value)) ? 1 : 0;
+                        }
+                        catch {
+                            return 0;
+                        }
+                    });
+                    // Register regexp_flags UDF for $regex with $options support
+                    db.function('regexp_flags', { deterministic: true }, (pattern, flags, value) => {
+                        if (typeof pattern !== 'string' || value === null || value === undefined)
+                            return 0;
+                        try {
+                            const f = typeof flags === 'string' ? flags : '';
+                            return new RegExp(pattern, f).test(String(value)) ? 1 : 0;
+                        }
+                        catch {
+                            return 0;
+                        }
+                    });
+                    if (this.verbose) {
+                        console.log(`SQLite database opened (node:sqlite): ${this.filePath}`);
+                    }
+                    return db;
+                };
+                this.db = this.shareKey
+                    ? sharedConnections.acquire(this.shareKey, openConnection)
+                    : openConnection();
+                resolve();
+            }
+            catch (err) {
+                console.error(`Error opening database ${this.filePath}:`, err.message);
+                this.db = null;
+                this.openPromise = null;
+                reject(err);
+            }
+        });
+        return this.openPromise;
+    }
+    async ensureConnected() {
+        if (!this.db || !this.openPromise) {
+            await this.connect();
+        }
+        else {
+            await this.openPromise;
+        }
+        if (!this.db) {
+            throw new Error('Database is not connected. Connection attempt failed.');
+        }
+        return this.db;
+    }
+    async run(sql, params = []) {
+        const dbInstance = await this.ensureConnected();
+        try {
+            const result = dbInstance.prepare(sql).run(...params);
+            return {
+                lastID: Number(result.lastInsertRowid),
+                changes: Number(result.changes),
+            };
+        }
+        catch (err) {
+            console.error(`Error running SQL: ${sql}`, err);
+            throw err;
+        }
+    }
+    async get(sql, params = []) {
+        const dbInstance = await this.ensureConnected();
+        try {
+            return dbInstance.prepare(sql).get(...params);
+        }
+        catch (err) {
+            console.error(`Error getting SQL: ${sql}`, err);
+            throw err;
+        }
+    }
+    async all(sql, params = []) {
+        const dbInstance = await this.ensureConnected();
+        try {
+            return dbInstance.prepare(sql).all(...params);
+        }
+        catch (err) {
+            console.error(`Error getting all SQL: ${sql}`, err);
+            throw err;
+        }
+    }
+    async exec(sql) {
+        const dbInstance = await this.ensureConnected();
+        try {
+            dbInstance.exec(sql);
+        }
+        catch (err) {
+            console.error(`Error executing SQL: ${sql}`, err);
+            throw err;
+        }
+    }
+    async close() {
+        if (this.openPromise) {
+            await this.openPromise;
+        }
+        if (this.db) {
+            try {
+                // When shared, only the last holder actually closes the handle.
+                const isLastHolder = this.shareKey
+                    ? sharedConnections.release(this.shareKey, this.db)
+                    : true;
+                if (isLastHolder) {
+                    this.db.close();
+                }
+                if (this.verbose) {
+                    console.log(isLastHolder
+                        ? `SQLite database closed (node:sqlite): ${this.filePath}`
+                        : `SQLite database released (still in use): ${this.filePath}`);
+                }
+            }
+            catch (err) {
+                console.error(`Error closing database ${this.filePath}:`, err.message);
+                throw err;
+            }
+            finally {
+                this.db = null;
+                this.openPromise = null;
+            }
+        }
+        else {
+            this.db = null;
+            this.openPromise = null;
+        }
+    }
+    /**
+     * Gets the underlying `node:sqlite` `DatabaseSync` instance.
+     * Useful for operations not covered by this wrapper.
+     */
+    async getDbInstance() {
+        return this.ensureConnected();
+    }
+}
+//# sourceMappingURL=node-sqlite.js.map

package/dist/adapters/node-sqlite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-sqlite.js","sourceRoot":"","sources":["../../src/adapters/node-sqlite.ts"],"names":[],"mappings":"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"}

package/dist/better-sqlite3.d.ts

@@ -0,0 +1,49 @@
+/**
+ * `better-sqlite3`-backed entry point for MongoLite.
+ *
+ * The main `@semics-tech/mongolite` entry point defaults to `NodeSqliteAdapter`, backed by
+ * Node.js's built-in `node:sqlite` module, which requires Node.js 22.5.0+. Import
+ * from `@semics-tech/mongolite/better-sqlite3` instead if you need to run on an older
+ * Node.js runtime, or you simply prefer the more battle-tested `better-sqlite3`
+ * native addon.
+ *
+ * `better-sqlite3` is an **optional dependency** of this package — install it
+ * yourself if it wasn't already pulled in:
+ *
+ * ```bash
+ * npm install better-sqlite3
+ * ```
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { MongoLite } from '@semics-tech/mongolite/better-sqlite3';
+ *
+ * const client = new MongoLite('./myapp.sqlite');
+ * await client.connect();
+ * const users = client.collection('users');
+ * await users.insertOne({ name: 'Alice', age: 30 });
+ * await client.close();
+ * ```
+ */
+import type { IDatabaseAdapter, MongoLiteOptions as DBMongoLiteOptions } from './db.js';
+import { MongoLite as MongoLiteBase, MongoLiteBaseOptions } from './mongo-client.js';
+export { MongoLiteCollection } from './collection.js';
+export * from './types.js';
+export { ChangeStream } from './changeStream.js';
+export type { ChangeStreamDocument, ChangeStreamOptions, ChangeOperationType, } from './changeStream.js';
+export type { IDatabaseAdapter } from './db.js';
+export { SQLiteDB } from './db.js';
+export interface MongoLiteClientOptions extends DBMongoLiteOptions {
+}
+/**
+ * MongoLite client backed by the `better-sqlite3` native addon.
+ *
+ * You can construct it with:
+ * - A file path string — uses the built-in `SQLiteDB` (`better-sqlite3`) adapter.
+ * - A `MongoLiteClientOptions` object — uses the built-in adapter with options.
+ * - An `IDatabaseAdapter` instance — use a custom adapter for other backends.
+ */
+export declare class MongoLite extends MongoLiteBase {
+    constructor(dbPathOrOptions: string | MongoLiteClientOptions | IDatabaseAdapter, options?: MongoLiteBaseOptions);
+}

package/dist/better-sqlite3.js

@@ -0,0 +1,60 @@
+/**
+ * `better-sqlite3`-backed entry point for MongoLite.
+ *
+ * The main `@semics-tech/mongolite` entry point defaults to `NodeSqliteAdapter`, backed by
+ * Node.js's built-in `node:sqlite` module, which requires Node.js 22.5.0+. Import
+ * from `@semics-tech/mongolite/better-sqlite3` instead if you need to run on an older
+ * Node.js runtime, or you simply prefer the more battle-tested `better-sqlite3`
+ * native addon.
+ *
+ * `better-sqlite3` is an **optional dependency** of this package — install it
+ * yourself if it wasn't already pulled in:
+ *
+ * ```bash
+ * npm install better-sqlite3
+ * ```
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { MongoLite } from '@semics-tech/mongolite/better-sqlite3';
+ *
+ * const client = new MongoLite('./myapp.sqlite');
+ * await client.connect();
+ * const users = client.collection('users');
+ * await users.insertOne({ name: 'Alice', age: 30 });
+ * await client.close();
+ * ```
+ */
+import { SQLiteDB } from './db.js';
+import { MongoLite as MongoLiteBase } from './mongo-client.js';
+export { MongoLiteCollection } from './collection.js';
+export * from './types.js';
+export { ChangeStream } from './changeStream.js';
+export { SQLiteDB } from './db.js';
+/**
+ * MongoLite client backed by the `better-sqlite3` native addon.
+ *
+ * You can construct it with:
+ * - A file path string — uses the built-in `SQLiteDB` (`better-sqlite3`) adapter.
+ * - A `MongoLiteClientOptions` object — uses the built-in adapter with options.
+ * - An `IDatabaseAdapter` instance — use a custom adapter for other backends.
+ */
+export class MongoLite extends MongoLiteBase {
+    constructor(dbPathOrOptions, options = {}) {
+        if (dbPathOrOptions &&
+            typeof dbPathOrOptions === 'object' &&
+            typeof dbPathOrOptions.connect === 'function' &&
+            typeof dbPathOrOptions.run === 'function' &&
+            typeof dbPathOrOptions.get === 'function' &&
+            typeof dbPathOrOptions.all === 'function' &&
+            typeof dbPathOrOptions.exec === 'function' &&
+            typeof dbPathOrOptions.close === 'function') {
+            super(dbPathOrOptions, options);
+        }
+        else {
+            super(new SQLiteDB(dbPathOrOptions), options);
+        }
+    }
+}
+//# sourceMappingURL=better-sqlite3.js.map

package/dist/better-sqlite3.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"better-sqlite3.js","sourceRoot":"","sources":["../src/better-sqlite3.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC,OAAO,EAAE,SAAS,IAAI,aAAa,EAAwB,MAAM,mBAAmB,CAAC;AAErF,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAOjD,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAInC;;;;;;;GAOG;AACH,MAAM,OAAO,SAAU,SAAQ,aAAa;IAC1C,YACE,eAAmE,EACnE,UAAgC,EAAE;QAElC,IACE,eAAe;YACf,OAAO,eAAe,KAAK,QAAQ;YACnC,OAAQ,eAAoC,CAAC,OAAO,KAAK,UAAU;YACnE,OAAQ,eAAoC,CAAC,GAAG,KAAK,UAAU;YAC/D,OAAQ,eAAoC,CAAC,GAAG,KAAK,UAAU;YAC/D,OAAQ,eAAoC,CAAC,GAAG,KAAK,UAAU;YAC/D,OAAQ,eAAoC,CAAC,IAAI,KAAK,UAAU;YAChE,OAAQ,eAAoC,CAAC,KAAK,KAAK,UAAU,EACjE,CAAC;YACD,KAAK,CAAC,eAAmC,EAAE,OAAO,CAAC,CAAC;QACtD,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,IAAI,QAAQ,CAAC,eAAkD,CAAC,EAAE,OAAO,CAAC,CAAC;QACnF,CAAC;IACH,CAAC;CACF"}

package/dist/cjs/adapters/browser.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrowserSqliteAdapter = void 0;
+/**
+ * Database adapter that wraps a {@link SqlJsDatabase} instance, enabling MongoLite
+ * to run in browser environments via [sql.js](https://sql.js.org/).
+ *
+ * ## Usage
+ *
+ * Install [sql.js](https://www.npmjs.com/package/sql.js) and initialise it before
+ * constructing the adapter:
+ *
+ * ```ts
+ * import initSqlJs from 'sql.js';
+ * import { MongoLite, BrowserSqliteAdapter } from '@semics-tech/mongolite';
+ *
+ * const SQL = await initSqlJs({
+ *   locateFile: (file) => `https://cdn.jsdelivr.net/npm/sql.js/dist/${file}`,
+ * });
+ * const sqlJsDb = new SQL.Database(); // in-memory; persist via OPFS or IndexedDB
+ *
+ * const client = new MongoLite(new BrowserSqliteAdapter(sqlJsDb));
+ * await client.connect();
+ * const users = client.collection('users');
+ * await users.insertOne({ name: 'Alice', age: 30 });
+ * await client.close();
+ * ```
+ *
+ * ## Limitations
+ *
+ * - **`$regex` queries are not supported** — sql.js does not ship with a `regexp()`
+ *   SQL function. Use JS-side filtering as a workaround.
+ * - **`lastID` / `changes`** are not exposed by the sql.js API. `run()` always
+ *   returns `{ lastID: 0, changes: 0 }`, which is safe because MongoLite does not
+ *   use these values internally.
+ * - **Persistence** — by default sql.js stores data in memory. For durable storage
+ *   use the OPFS back-end or export the database buffer to IndexedDB.
+ */
+class BrowserSqliteAdapter {
+    /**
+     * @param db An initialised sql.js `Database` instance.
+     */
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * No-op: sql.js Database is already open on construction.
+     */
+    async connect() {
+        // Nothing to do — the sql.js Database is ready to use immediately.
+    }
+    /**
+     * Closes the underlying sql.js Database and frees its WASM memory.
+     */
+    async close() {
+        this.db.close();
+    }
+    /**
+     * Executes a DML statement (INSERT, UPDATE, DELETE) with optional bound parameters.
+     * Returns `{ lastID: 0, changes: 0 }` — sql.js does not expose these values.
+     */
+    async run(sql, params = []) {
+        this.db.run(sql, params);
+        return { lastID: 0, changes: 0 };
+    }
+    /**
+     * Executes a SQL query and returns the first matching row, or `undefined`.
+     */
+    async get(sql, params = []) {
+        const stmt = this.db.prepare(sql);
+        try {
+            stmt.bind(params);
+            if (stmt.step()) {
+                return stmt.getAsObject();
+            }
+            return undefined;
+        }
+        finally {
+            stmt.free();
+        }
+    }
+    /**
+     * Executes a SQL query and returns all matching rows.
+     */
+    async all(sql, params = []) {
+        const stmt = this.db.prepare(sql);
+        try {
+            stmt.bind(params);
+            const rows = [];
+            while (stmt.step()) {
+                rows.push(stmt.getAsObject());
+            }
+            return rows;
+        }
+        finally {
+            stmt.free();
+        }
+    }
+    /**
+     * Executes one or more SQL statements (DDL, transactions, etc.).
+     */
+    async exec(sql) {
+        this.db.exec(sql);
+    }
+}
+exports.BrowserSqliteAdapter = BrowserSqliteAdapter;