@semics-tech/mongolite 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 YOUR_NAME
+
+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,179 @@
+# MongoLite
+
+[![CI](https://github.com/semics-tech/mongolite/actions/workflows/ci.yml/badge.svg)](https://github.com/semics-tech/mongolite/actions/workflows/ci.yml)
+[![NPM version](https://img.shields.io/npm/v/@semics-tech/mongolite.svg)](https://www.npmjs.com/package/@semics-tech/mongolite)
+[![Codecov](https://codecov.io/gh/semics-tech/mongolite/branch/master/graph/badge.svg)](https://codecov.io/gh/semics-tech/mongolite)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+A MongoDB-like client backed by SQLite. Use a familiar MongoDB API with the simplicity of a local file-based database — no server required.
+
+## Why MongoLite?
+
+- You want a MongoDB-style API without running a MongoDB server
+- You need a lightweight, embedded database for local apps, CLIs, or testing
+- You want simple file-based persistence with zero infrastructure overhead
+
+## Features
+
+- **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
+- **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
+- **TypeScript** — fully typed with strict mode
+
+## Installation
+
+```bash
+npm install @semics-tech/mongolite
+```
+
+## Quick Start
+
+```typescript
+import { MongoLite } from '@semics-tech/mongolite';
+
+async function main() {
+  const client = new MongoLite('./myapp.sqlite');
+  // Use ':memory:' for an ephemeral in-memory database
+
+  const users = client.collection('users');
+
+  // Insert
+  const result = await users.insertOne({ name: 'Alice', age: 30 });
+
+  // Find
+  const user = await users.findOne({ name: 'Alice' });
+
+  // Update
+  await users.updateOne({ name: 'Alice' }, { $set: { age: 31 } });
+
+  // Delete
+  await users.deleteOne({ name: 'Alice' });
+
+  await client.close();
+}
+
+main();
+```
+
+## How does it compare?
+
+| | MongoLite | lowdb | better-sqlite3 (raw) | NeDB | PouchDB | MongoDB |
+|---|---|---|---|---|---|---|
+| MongoDB query API (`$set`, `$elemMatch`, aggregation...) | ✅ | ❌ (plain object access) | ❌ (raw SQL) | ✅ | ❌ (Mango/CouchDB-style) | ✅ |
+| Runs in the browser | ✅ (sql.js) | ✅ | ❌ (native binding) | ✅ | ✅ (IndexedDB) | ❌ |
+| Runs on the edge (Cloudflare Durable Objects) | ✅ | ❌ | ❌ (native binding) | ❌ | ❌ | ❌ |
+| Zero infrastructure (no server process) | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
+| TypeScript, strict mode | ✅ | ✅ | ✅ | ⚠️ (community types) | ⚠️ (community types) | ✅ |
+| Actively maintained | ✅ | ✅ | ✅ | ❌ (unmaintained) | ⚠️ (slow-moving) | ✅ |
+
+MongoLite's niche: the MongoDB query API you already know, running anywhere SQLite runs — a local file, an in-memory test database, the browser, or a Cloudflare Durable Object — without standing up a MongoDB server.
+
+## Documentation
+
+| Topic | Description |
+|-------|-------------|
+| [API Reference](./docs/API.md) | Full API docs: methods, query operators, update operators |
+| [Change Streams](./docs/CHANGE_STREAMS.md) | Real-time change tracking with `collection.watch()` |
+| [JSON Safety](./docs/JSON_SAFETY.md) | Document validation and corrupted data recovery |
+| [Query Debugger](./docs/DEBUGGER.md) | Interactive CLI for debugging queries and inspecting SQL |
+| [Benchmarks](./docs/BENCHMARKS.md) | Performance benchmarks and storage characteristics |
+| [Cloudflare Durable Objects](./docs/CLOUDFLARE.md) | Using MongoLite inside a Cloudflare Durable Object |
+
+## Backend Examples
+
+### SQLite file (Node.js / Bun)
+
+```typescript
+import { MongoLite } from '@semics-tech/mongolite';
+
+const client = new MongoLite('./myapp.sqlite');
+await client.connect();
+const users = client.collection('users');
+await users.insertOne({ name: 'Alice', age: 30 });
+await client.close();
+```
+
+### In-memory (tests / ephemeral)
+
+```typescript
+import { MongoLite } from '@semics-tech/mongolite';
+
+const client = new MongoLite(':memory:');
+await client.connect();
+const users = client.collection('users');
+await users.insertOne({ name: 'Alice', age: 30 });
+// Data is discarded when the process exits
+await client.close();
+```
+
+### Browser (via sql.js)
+
+Requires [sql.js](https://www.npmjs.com/package/sql.js) (`npm install sql.js`).
+
+```typescript
+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; use OPFS/IndexedDB for persistence
+
+const client = new MongoLite(new BrowserSqliteAdapter(sqlJsDb));
+await client.connect();
+const users = client.collection('users');
+await users.insertOne({ name: 'Alice', age: 30 });
+console.log(await users.findOne({ name: 'Alice' }));
+await client.close();
+```
+
+### Cloudflare Durable Objects
+
+```typescript
+import { DurableObject } from 'cloudflare:workers';
+import { MongoLite, CloudflareDurableObjectAdapter } from '@semics-tech/mongolite/cloudflare';
+
+export class MyDurableObject extends DurableObject {
+  private client: MongoLite;
+
+  constructor(ctx: DurableObjectState, env: Env) {
+    super(ctx, env);
+    // Pass ctx.storage.sql — no file path needed
+    this.client = new MongoLite(new CloudflareDurableObjectAdapter(ctx.storage.sql));
+    ctx.blockConcurrencyWhile(() => this.client.collection('users').ensureTable());
+  }
+
+  async fetch(request: Request) {
+    const users = this.client.collection('users');
+    await users.insertOne({ name: 'Alice', age: 30 });
+    return Response.json(await users.findOne({ name: 'Alice' }));
+  }
+}
+```
+
+> See [docs/CLOUDFLARE.md](./docs/CLOUDFLARE.md) for the full guide, supported operations, and limitations.
+
+## Development
+
+```bash
+git clone https://github.com/semics-tech/mongolite.git
+cd mongolite
+npm install
+npm test          # Run tests
+npm run build     # Compile TypeScript
+npm run lint      # Lint code
+```
+
+## Contributing
+
+Contributions are welcome! Please read [CONTRIBUTING.md](./CONTRIBUTING.md) before submitting a pull request.
+
+## License
+
+[MIT](./LICENSE)

package/dist/adapters/browser.d.ts

@@ -0,0 +1,97 @@
+import type { IDatabaseAdapter } from '../db.js';
+type SqlJsColumnType = string | number | bigint | null | Uint8Array;
+type SqlJsBindParams = SqlJsColumnType[] | Record<string, SqlJsColumnType> | null;
+/**
+ * Minimal interface representing a sql.js Statement object.
+ * @see https://sql.js.org/documentation/Statement.html
+ */
+export interface SqlJsStatement {
+    bind(params?: SqlJsBindParams): boolean;
+    step(): boolean;
+    getAsObject(params?: SqlJsBindParams | null): Record<string, SqlJsColumnType>;
+    free(): boolean;
+}
+/**
+ * Minimal interface representing a sql.js Database object.
+ * @see https://sql.js.org/documentation/Database.html
+ */
+export interface SqlJsDatabase {
+    run(sql: string, params?: SqlJsBindParams): SqlJsDatabase;
+    exec(sql: string): Array<{
+        columns: string[];
+        values: SqlJsColumnType[][];
+    }>;
+    prepare(sql: string): SqlJsStatement;
+    close(): void;
+}
+/**
+ * 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.
+ */
+export declare class BrowserSqliteAdapter implements IDatabaseAdapter {
+    private readonly db;
+    /**
+     * @param db An initialised sql.js `Database` instance.
+     */
+    constructor(db: SqlJsDatabase);
+    /**
+     * No-op: sql.js Database is already open on construction.
+     */
+    connect(): Promise<void>;
+    /**
+     * Closes the underlying sql.js Database and frees its WASM memory.
+     */
+    close(): Promise<void>;
+    /**
+     * Executes a DML statement (INSERT, UPDATE, DELETE) with optional bound parameters.
+     * Returns `{ lastID: 0, changes: 0 }` — sql.js does not expose these values.
+     */
+    run(sql: string, params?: unknown[]): Promise<{
+        lastID: number;
+        changes: number;
+    }>;
+    /**
+     * Executes a SQL query and returns the first matching row, or `undefined`.
+     */
+    get<T>(sql: string, params?: unknown[]): Promise<T | undefined>;
+    /**
+     * Executes a SQL query and returns all matching rows.
+     */
+    all<T>(sql: string, params?: unknown[]): Promise<T[]>;
+    /**
+     * Executes one or more SQL statements (DDL, transactions, etc.).
+     */
+    exec(sql: string): Promise<void>;
+}
+export {};

package/dist/adapters/browser.js

@@ -0,0 +1,103 @@
+/**
+ * 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.
+ */
+export 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);
+    }
+}
+//# sourceMappingURL=browser.js.map

package/dist/adapters/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../../src/adapters/browser.ts"],"names":[],"mappings":"AA2BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,OAAO,oBAAoB;IAG/B;;OAEG;IACH,YAAY,EAAiB;QAC3B,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;IACf,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAO;QACX,mEAAmE;IACrE,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC;IAClB,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,SAAoB,EAAE;QAC3C,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,MAA2B,CAAC,CAAC;QAC9C,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;IACnC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,GAAG,CAAI,GAAW,EAAE,SAAoB,EAAE;QAC9C,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,CAAC;YACH,IAAI,CAAC,IAAI,CAAC,MAA2B,CAAC,CAAC;YACvC,IAAI,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;gBAChB,OAAO,IAAI,CAAC,WAAW,EAAO,CAAC;YACjC,CAAC;YACD,OAAO,SAAS,CAAC;QACnB,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,GAAG,CAAI,GAAW,EAAE,SAAoB,EAAE;QAC9C,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,CAAC;YACH,IAAI,CAAC,IAAI,CAAC,MAA2B,CAAC,CAAC;YACvC,MAAM,IAAI,GAAQ,EAAE,CAAC;YACrB,OAAO,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;gBACnB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAO,CAAC,CAAC;YACrC,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,IAAI,CAAC,GAAW;QACpB,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACpB,CAAC;CACF"}

package/dist/adapters/cloudflare.d.ts

@@ -0,0 +1,106 @@
+import { IDatabaseAdapter } from '../db.js';
+/**
+ * Allowed scalar binding values accepted by Cloudflare's SqlStorage.exec().
+ */
+export type SqlStorageValue = string | number | boolean | null | ArrayBuffer;
+/**
+ * Minimal interface for the cursor returned by SqlStorage.exec().
+ * This matches the Cloudflare Durable Objects SqlStorage API.
+ */
+export interface SqlStorageCursor<T = Record<string, SqlStorageValue>> {
+    toArray(): T[];
+    one(): T;
+    readonly rowsRead: number;
+    readonly rowsWritten: number;
+    readonly columnNames: readonly string[];
+}
+/**
+ * Minimal interface for the Cloudflare Durable Objects SqlStorage API.
+ * Pass `ctx.storage.sql` from your Durable Object to the adapter constructor.
+ *
+ * @see https://developers.cloudflare.com/durable-objects/api/sqlite-storage-api/
+ */
+export interface SqlStorage {
+    exec<T = Record<string, SqlStorageValue>>(query: string, ...bindings: SqlStorageValue[]): SqlStorageCursor<T>;
+}
+/**
+ * Database adapter that wraps the Cloudflare Durable Objects `SqlStorage` API,
+ * allowing MongoLite to be used inside a Cloudflare Durable Object.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { DurableObject } from 'cloudflare:workers';
+ * import { MongoLite, CloudflareDurableObjectAdapter } from '@semics-tech/mongolite/cloudflare';
+ *
+ * export class MyDurableObject extends DurableObject {
+ *   private client: MongoLite;
+ *
+ *   constructor(ctx: DurableObjectState, env: Env) {
+ *     super(ctx, env);
+ *     const adapter = new CloudflareDurableObjectAdapter(ctx.storage.sql);
+ *     this.client = new MongoLite(adapter);
+ *   }
+ *
+ *   async fetch(request: Request) {
+ *     await this.client.connect();
+ *     const users = this.client.collection('users');
+ *     await users.insertOne({ name: 'Alice', age: 30 });
+ *     const user = await users.findOne({ name: 'Alice' });
+ *     return Response.json(user);
+ *   }
+ * }
+ * ```
+ *
+ * ## Limitations
+ *
+ * - **`$regex` queries are not supported.** Cloudflare's SQLite does not allow custom
+ *   SQL functions, so the `regexp()` UDF registered by the default Node.js adapter is
+ *   unavailable. Queries using `$regex` will throw a SQL error at runtime.
+ * - `WAL` mode and most `PRAGMA` statements are not available in Cloudflare Durable
+ *   Objects (Cloudflare manages this internally).
+ * - Change Streams (`collection.watch()`) use SQL triggers and a change-log table.
+ *   They work in Cloudflare Durable Objects, but the polling mechanism relies on
+ *   `setInterval`, which is supported in the Workers runtime.
+ */
+export declare class CloudflareDurableObjectAdapter implements IDatabaseAdapter {
+    private readonly sql;
+    /**
+     * @param sql The `SqlStorage` instance from a Cloudflare Durable Object context
+     *            (i.e. `ctx.storage.sql`).
+     */
+    constructor(sql: SqlStorage);
+    /**
+     * No-op: Cloudflare Durable Objects manage the storage lifecycle automatically.
+     */
+    connect(): Promise<void>;
+    /**
+     * No-op: Cloudflare Durable Objects manage the storage lifecycle automatically.
+     */
+    close(): Promise<void>;
+    /**
+     * Executes a SQL statement that does not return rows (INSERT, UPDATE, DELETE, DDL).
+     */
+    run(sql: string, params?: unknown[]): Promise<{
+        lastID: number;
+        changes: number;
+    }>;
+    /**
+     * Executes a SQL query and returns the first matching row, or `undefined`.
+     */
+    get<T>(sql: string, params?: unknown[]): Promise<T | undefined>;
+    /**
+     * Executes a SQL query and returns all matching rows.
+     */
+    all<T>(sql: string, params?: unknown[]): Promise<T[]>;
+    /**
+     * Executes a single SQL statement (DDL, transactions, etc.).
+     *
+     * Cloudflare's `SqlStorage.exec` only supports one statement at a time, and
+     * some valid statements (e.g. `CREATE TRIGGER ... BEGIN ...; ...; END;`)
+     * contain internal semicolons. Callers must therefore pass exactly one
+     * statement per call; this method will not attempt to split multi-statement
+     * SQL strings.
+     */
+    exec(sql: string): Promise<void>;
+}

package/dist/adapters/cloudflare.js

@@ -0,0 +1,94 @@
+/**
+ * Database adapter that wraps the Cloudflare Durable Objects `SqlStorage` API,
+ * allowing MongoLite to be used inside a Cloudflare Durable Object.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { DurableObject } from 'cloudflare:workers';
+ * import { MongoLite, CloudflareDurableObjectAdapter } from '@semics-tech/mongolite/cloudflare';
+ *
+ * export class MyDurableObject extends DurableObject {
+ *   private client: MongoLite;
+ *
+ *   constructor(ctx: DurableObjectState, env: Env) {
+ *     super(ctx, env);
+ *     const adapter = new CloudflareDurableObjectAdapter(ctx.storage.sql);
+ *     this.client = new MongoLite(adapter);
+ *   }
+ *
+ *   async fetch(request: Request) {
+ *     await this.client.connect();
+ *     const users = this.client.collection('users');
+ *     await users.insertOne({ name: 'Alice', age: 30 });
+ *     const user = await users.findOne({ name: 'Alice' });
+ *     return Response.json(user);
+ *   }
+ * }
+ * ```
+ *
+ * ## Limitations
+ *
+ * - **`$regex` queries are not supported.** Cloudflare's SQLite does not allow custom
+ *   SQL functions, so the `regexp()` UDF registered by the default Node.js adapter is
+ *   unavailable. Queries using `$regex` will throw a SQL error at runtime.
+ * - `WAL` mode and most `PRAGMA` statements are not available in Cloudflare Durable
+ *   Objects (Cloudflare manages this internally).
+ * - Change Streams (`collection.watch()`) use SQL triggers and a change-log table.
+ *   They work in Cloudflare Durable Objects, but the polling mechanism relies on
+ *   `setInterval`, which is supported in the Workers runtime.
+ */
+export class CloudflareDurableObjectAdapter {
+    /**
+     * @param sql The `SqlStorage` instance from a Cloudflare Durable Object context
+     *            (i.e. `ctx.storage.sql`).
+     */
+    constructor(sql) {
+        this.sql = sql;
+    }
+    /**
+     * No-op: Cloudflare Durable Objects manage the storage lifecycle automatically.
+     */
+    async connect() {
+        // Nothing to do — the SqlStorage instance is already live.
+    }
+    /**
+     * No-op: Cloudflare Durable Objects manage the storage lifecycle automatically.
+     */
+    async close() {
+        // Nothing to do — storage is managed by the Durable Object runtime.
+    }
+    /**
+     * Executes a SQL statement that does not return rows (INSERT, UPDATE, DELETE, DDL).
+     */
+    async run(sql, params = []) {
+        const cursor = this.sql.exec(sql, ...params);
+        return { lastID: 0, changes: cursor.rowsWritten };
+    }
+    /**
+     * Executes a SQL query and returns the first matching row, or `undefined`.
+     */
+    async get(sql, params = []) {
+        const rows = this.sql.exec(sql, ...params).toArray();
+        return rows[0];
+    }
+    /**
+     * Executes a SQL query and returns all matching rows.
+     */
+    async all(sql, params = []) {
+        return this.sql.exec(sql, ...params).toArray();
+    }
+    /**
+     * Executes a single SQL statement (DDL, transactions, etc.).
+     *
+     * Cloudflare's `SqlStorage.exec` only supports one statement at a time, and
+     * some valid statements (e.g. `CREATE TRIGGER ... BEGIN ...; ...; END;`)
+     * contain internal semicolons. Callers must therefore pass exactly one
+     * statement per call; this method will not attempt to split multi-statement
+     * SQL strings.
+     */
+    async exec(sql) {
+        this.sql.exec(sql);
+    }
+}
+//# sourceMappingURL=cloudflare.js.map

package/dist/adapters/cloudflare.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare.js","sourceRoot":"","sources":["../../src/adapters/cloudflare.ts"],"names":[],"mappings":"AAgCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,OAAO,8BAA8B;IAGzC;;;OAGG;IACH,YAAY,GAAe;QACzB,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACjB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAO;QACX,2DAA2D;IAC7D,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,KAAK;QACT,oEAAoE;IACtE,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,SAAoB,EAAE;QAC3C,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,GAAI,MAA4B,CAAC,CAAC;QACpE,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,WAAW,EAAE,CAAC;IACpD,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,GAAG,CAAI,GAAW,EAAE,SAAoB,EAAE;QAC9C,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAI,GAAG,EAAE,GAAI,MAA4B,CAAC,CAAC,OAAO,EAAE,CAAC;QAC/E,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC;IACjB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,GAAG,CAAI,GAAW,EAAE,SAAoB,EAAE;QAC9C,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAI,GAAG,EAAE,GAAI,MAA4B,CAAC,CAAC,OAAO,EAAE,CAAC;IAC3E,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,IAAI,CAAC,GAAW;QACpB,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACrB,CAAC;CACF"}

package/dist/bin/mongolite-debug.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};