@semics-tech/mongolite 1.0.0 → 1.2.0

package/dist/cjs/adapters/cloudflare.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CloudflareDurableObjectAdapter = void 0;
+/**
+ * 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.
+ */
+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);
+    }
+}
+exports.CloudflareDurableObjectAdapter = CloudflareDurableObjectAdapter;

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

@@ -0,0 +1,248 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NodeSqliteAdapter = void 0;
+exports.sharedConnectionCount = sharedConnectionCount;
+const node_sqlite_1 = require("node:sqlite");
+const node_path_1 = __importDefault(require("node:path"));
+const connection_registry_js_1 = require("../utils/connection-registry.js");
+/** Shared `node:sqlite` handles for this process, keyed by connection identity. */
+const sharedConnections = new connection_registry_js_1.ConnectionRegistry();
+/** Exposed for tests and diagnostics. */
+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.
+ */
+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 = connection_registry_js_1.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 ?? connection_registry_js_1.DEFAULT_BUSY_TIMEOUT_MS;
+            shared = dbPathOrOptions.shared ?? false;
+        }
+        this.shareKey =
+            shared && (0, connection_registry_js_1.isShareablePath)(this.filePath)
+                ? (0, connection_registry_js_1.buildConnectionKey)({
+                    backend: 'node:sqlite',
+                    filePath: node_path_1.default.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 node_sqlite_1.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();
+    }
+}
+exports.NodeSqliteAdapter = NodeSqliteAdapter;

package/dist/cjs/better-sqlite3.js

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * `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();
+ * ```
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MongoLite = exports.SQLiteDB = exports.ChangeStream = exports.MongoLiteCollection = void 0;
+const db_js_1 = require("./db.js");
+const mongo_client_js_1 = require("./mongo-client.js");
+var collection_js_1 = require("./collection.js");
+Object.defineProperty(exports, "MongoLiteCollection", { enumerable: true, get: function () { return collection_js_1.MongoLiteCollection; } });
+__exportStar(require("./types.js"), exports);
+var changeStream_js_1 = require("./changeStream.js");
+Object.defineProperty(exports, "ChangeStream", { enumerable: true, get: function () { return changeStream_js_1.ChangeStream; } });
+var db_js_2 = require("./db.js");
+Object.defineProperty(exports, "SQLiteDB", { enumerable: true, get: function () { return db_js_2.SQLiteDB; } });
+/**
+ * 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.
+ */
+class MongoLite extends mongo_client_js_1.MongoLite {
+    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 db_js_1.SQLiteDB(dbPathOrOptions), options);
+        }
+    }
+}
+exports.MongoLite = MongoLite;

package/dist/cjs/bin/mongolite-debug.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const query_debugger_js_1 = require("../debugger/query-debugger.js");
+const path_1 = __importDefault(require("path"));
+// CLI argument parsing
+function parseArgs() {
+    const args = process.argv.slice(2);
+    const options = {};
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--verbose' || arg === '-v') {
+            options.verbose = true;
+        }
+        else if (arg === '--collection' || arg === '-c') {
+            options.collection = args[++i];
+        }
+        else if (arg === '--database' || arg === '-d') {
+            options.database = args[++i];
+        }
+        else if (arg === '--help' || arg === '-h') {
+            options.help = true;
+        }
+    }
+    return options;
+}
+function showHelp() {
+    console.log('MongoLite Query Debugger');
+    console.log('');
+    console.log('Interactive debugging tool for MongoLite queries.');
+    console.log('');
+    console.log('Usage: npx mongolite-debug [options]');
+    console.log('');
+    console.log('Options:');
+    console.log('  -d, --database <path>     Database file path (default: ./mongolite.db)');
+    console.log('  -c, --collection <name>   Initial collection to use');
+    console.log('  -v, --verbose             Enable verbose output');
+    console.log('  -h, --help                Show this help');
+    console.log('');
+    console.log('Interactive Commands:');
+    console.log('  .help                     Show available commands');
+    console.log('  .collections              List all collections');
+    console.log('  .use <collection>         Select a collection to work with');
+    console.log('  .find <filter>            Convert find filter to SQL and execute');
+    console.log('  .sql <query>              Execute raw SQL query');
+    console.log('  .last                     Show last generated SQL');
+    console.log('  .sample [count]           Show sample documents from current collection');
+    console.log('  .exit                     Exit the debugger');
+    console.log('');
+    console.log('Examples:');
+    console.log('  npx mongolite-debug -d ./myapp.db -c users');
+    console.log('  npx mongolite-debug --verbose');
+    console.log('');
+    console.log('  # Inside the debugger:');
+    console.log('  .use users');
+    console.log('  .find {"age": {"$gt": 25}}');
+    console.log('  .sql SELECT * FROM users WHERE json_extract(data, "$.age") > 25');
+    console.log('');
+}
+async function main() {
+    const options = parseArgs();
+    if (options.help) {
+        showHelp();
+        process.exit(0);
+    }
+    // Set default database path if not provided
+    if (!options.database) {
+        // Look for common database files in the current directory
+        const cwd = process.cwd();
+        const commonNames = [
+            'mongolite.db',
+            'mongolite.sqlite',
+            'database.db',
+            'database.sqlite',
+            'app.db',
+            'app.sqlite',
+        ];
+        // Check if any common database files exist
+        const { existsSync } = await Promise.resolve().then(() => __importStar(require('fs')));
+        let foundDb = false;
+        for (const name of commonNames) {
+            const dbPath = path_1.default.join(cwd, name);
+            if (existsSync(dbPath)) {
+                options.database = dbPath;
+                foundDb = true;
+                break;
+            }
+        }
+        if (!foundDb) {
+            options.database = path_1.default.join(cwd, 'mongolite.db');
+        }
+    }
+    console.log('🔍 MongoLite Query Debugger (npx version)');
+    console.log(`📁 Database: ${options.database}`);
+    if (options.collection) {
+        console.log(`📋 Initial collection: ${options.collection}`);
+    }
+    console.log('');
+    try {
+        const queryDebugger = new query_debugger_js_1.QueryDebugger(options);
+        await queryDebugger.start();
+    }
+    catch (error) {
+        console.error('Fatal error:', error instanceof Error ? error.message : error);
+        if (error instanceof Error && error.message.includes('SQLITE_CANTOPEN')) {
+            console.error('');
+            console.error('💡 Tip: Make sure the database file exists or specify a different path with -d');
+            console.error('   Example: npx mongolite-debug -d ./path/to/your/database.db');
+        }
+        process.exit(1);
+    }
+}
+main().catch((error) => {
+    console.error('Unexpected error:', error);
+    process.exit(1);
+});