@semics-tech/mongolite 1.2.0 → 1.4.0

package/dist/cjs/cli/ui.js

@@ -0,0 +1,431 @@
+"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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PromptCancelledError = exports.style = exports.isInteractive = void 0;
+exports.displayWidth = displayWidth;
+exports.truncate = truncate;
+exports.terminalWidth = terminalWidth;
+exports.select = select;
+exports.closePrompts = closePrompts;
+exports.question = question;
+exports.text = text;
+exports.multilineText = multilineText;
+exports.confirm = confirm;
+exports.pause = pause;
+exports.heading = heading;
+exports.info = info;
+exports.warn = warn;
+exports.error = error;
+exports.success = success;
+/**
+ * Small, dependency-free terminal UI helpers used by the guided MongoLite CLI.
+ *
+ * Everything degrades gracefully:
+ * - When stdin/stdout is a TTY the prompts are interactive (arrow keys, filtering).
+ * - When it is not (pipes, CI, dumb terminals) the same prompts fall back to a
+ *   numbered list read line-by-line, so the CLI stays scriptable.
+ */
+const readline = __importStar(require("node:readline"));
+const NO_COLOR = process.env.NO_COLOR !== undefined || process.env.TERM === 'dumb';
+const isInteractive = () => Boolean(process.stdin.isTTY && process.stdout.isTTY && !process.env.MONGOLITE_NON_INTERACTIVE);
+exports.isInteractive = isInteractive;
+const wrap = (open, close) => (text) => NO_COLOR || !process.stdout.isTTY ? text : `\u001b[${open}m${text}\u001b[${close}m`;
+exports.style = {
+    bold: wrap('1', '22'),
+    dim: wrap('2', '22'),
+    italic: wrap('3', '23'),
+    underline: wrap('4', '24'),
+    red: wrap('31', '39'),
+    green: wrap('32', '39'),
+    yellow: wrap('33', '39'),
+    blue: wrap('34', '39'),
+    magenta: wrap('35', '39'),
+    cyan: wrap('36', '39'),
+    grey: wrap('90', '39'),
+};
+/** Visible width of a string, ignoring ANSI escape sequences. */
+function displayWidth(text) {
+    return text.replace(/\u001b\[[0-9;]*m/g, '').length;
+}
+/** Truncate to `max` visible characters, appending an ellipsis when cut. */
+function truncate(text, max) {
+    if (max <= 0)
+        return '';
+    if (text.length <= max)
+        return text;
+    if (max <= 1)
+        return text.slice(0, max);
+    return `${text.slice(0, max - 1)}…`;
+}
+function terminalWidth() {
+    return Math.max(40, process.stdout.columns || 100);
+}
+/** Thrown when the user aborts a prompt with Esc or Ctrl+C. */
+class PromptCancelledError extends Error {
+    constructor() {
+        super('Prompt cancelled');
+        this.name = 'PromptCancelledError';
+    }
+}
+exports.PromptCancelledError = PromptCancelledError;
+function selectableIndexes(choices) {
+    return choices.map((c, i) => (c.separator ? -1 : i)).filter((i) => i >= 0);
+}
+/**
+ * Ask the user to pick one of `choices`.
+ * Interactive terminals get an arrow-key menu with type-to-filter; everything
+ * else gets a numbered list.
+ */
+async function select(options) {
+    if (options.choices.length === 0) {
+        throw new Error(`Nothing to choose from for: ${options.message}`);
+    }
+    const selectable = selectableIndexes(options.choices);
+    if (selectable.length === 1 && options.choices.length === 1) {
+        // Nothing to decide - tell the user what was picked for them and move on.
+        const only = options.choices[selectable[0]];
+        process.stdout.write(`${exports.style.green('?')} ${exports.style.bold(options.message)} ${exports.style.cyan(only.label)} ${exports.style.grey('(only option)')}\n`);
+        return only.value;
+    }
+    return (0, exports.isInteractive)() ? interactiveSelect(options) : fallbackSelect(options);
+}
+async function interactiveSelect(options) {
+    const { message, choices } = options;
+    const pageSize = Math.min(options.pageSize ?? 12, Math.max(3, (process.stdout.rows || 24) - 6));
+    let filter = '';
+    let cursor = 0;
+    let renderedLines = 0;
+    const visible = () => {
+        const lowered = filter.toLowerCase();
+        return choices
+            .map((choice, index) => ({ choice, index }))
+            .filter(({ choice }) => {
+            if (!filter)
+                return true;
+            if (choice.separator)
+                return false;
+            return `${choice.label} ${choice.hint ?? ''}`.toLowerCase().includes(lowered);
+        });
+    };
+    const selectablePositions = (list) => list.map((entry, pos) => (entry.choice.separator ? -1 : pos)).filter((pos) => pos >= 0);
+    const initial = options.initialIndex ?? 0;
+    {
+        const list = visible();
+        const positions = selectablePositions(list);
+        const wanted = list.findIndex((entry) => entry.index === initial);
+        cursor = positions.includes(wanted) ? wanted : (positions[0] ?? 0);
+    }
+    const clear = () => {
+        if (renderedLines > 0) {
+            process.stdout.write(`\u001b[${renderedLines}A`);
+            process.stdout.write('\u001b[0J');
+        }
+        renderedLines = 0;
+    };
+    const render = () => {
+        clear();
+        const width = terminalWidth();
+        const list = visible();
+        const positions = selectablePositions(list);
+        if (positions.length && !positions.includes(cursor)) {
+            cursor = positions[0];
+        }
+        const lines = [];
+        const filterSuffix = filter ? ` ${exports.style.yellow(`/${filter}`)}` : '';
+        lines.push(`${exports.style.green('?')} ${exports.style.bold(message)}${filterSuffix}`);
+        lines.push(exports.style.grey(options.hint ?? '  ↑/↓ move · type to filter · enter to select · esc to go back'));
+        // Scroll window so the cursor stays visible.
+        let start = 0;
+        if (list.length > pageSize) {
+            start = Math.min(Math.max(0, cursor - Math.floor(pageSize / 2)), list.length - pageSize);
+        }
+        const window = list.slice(start, start + pageSize);
+        if (window.length === 0) {
+            lines.push(exports.style.grey('  no matches'));
+        }
+        window.forEach((entry, offset) => {
+            const pos = start + offset;
+            const { choice } = entry;
+            if (choice.separator) {
+                lines.push(exports.style.grey(`  ${choice.label}`));
+                return;
+            }
+            const active = pos === cursor;
+            const pointer = active ? exports.style.cyan('❯') : ' ';
+            const label = active ? exports.style.cyan(choice.label) : choice.label;
+            const hint = choice.hint ? ` ${exports.style.grey(choice.hint)}` : '';
+            const line = `${pointer} ${label}${hint}`;
+            lines.push(displayWidth(line) > width ? truncate(line, width) : line);
+        });
+        if (list.length > pageSize) {
+            lines.push(exports.style.grey(`  … ${start + window.length}/${list.length}`));
+        }
+        process.stdout.write(`${lines.join('\n')}\n`);
+        renderedLines = lines.length;
+    };
+    return new Promise((resolve, reject) => {
+        readline.emitKeypressEvents(process.stdin);
+        const wasRaw = process.stdin.isRaw;
+        process.stdin.setRawMode(true);
+        process.stdin.resume();
+        const finish = (fn) => {
+            process.stdin.removeListener('keypress', onKeypress);
+            process.stdin.setRawMode(Boolean(wasRaw));
+            process.stdin.pause();
+            fn();
+        };
+        const onKeypress = (str, key) => {
+            const list = visible();
+            const positions = selectablePositions(list);
+            if (key.ctrl && key.name === 'c') {
+                clear();
+                finish(() => {
+                    process.stdout.write(exports.style.grey('Cancelled.\n'));
+                    process.exit(0);
+                });
+                return;
+            }
+            switch (key.name) {
+                case 'escape':
+                    clear();
+                    finish(() => reject(new PromptCancelledError()));
+                    return;
+                case 'up': {
+                    const at = positions.indexOf(cursor);
+                    cursor = positions[(at - 1 + positions.length) % positions.length] ?? cursor;
+                    render();
+                    return;
+                }
+                case 'down': {
+                    const at = positions.indexOf(cursor);
+                    cursor = positions[(at + 1) % positions.length] ?? cursor;
+                    render();
+                    return;
+                }
+                case 'pageup':
+                    cursor = positions[0] ?? cursor;
+                    render();
+                    return;
+                case 'pagedown':
+                    cursor = positions[positions.length - 1] ?? cursor;
+                    render();
+                    return;
+                case 'return':
+                case 'enter': {
+                    const chosen = list[cursor];
+                    if (!chosen || chosen.choice.separator)
+                        return;
+                    clear();
+                    process.stdout.write(`${exports.style.green('?')} ${exports.style.bold(message)} ${exports.style.cyan(chosen.choice.label)}\n`);
+                    finish(() => resolve(chosen.choice.value));
+                    return;
+                }
+                case 'backspace':
+                    filter = filter.slice(0, -1);
+                    render();
+                    return;
+                default:
+                    break;
+            }
+            if (str && !key.ctrl && !key.meta && str >= ' ' && str <= '~') {
+                filter += str;
+                render();
+            }
+        };
+        process.stdin.on('keypress', onKeypress);
+        render();
+    });
+}
+async function fallbackSelect(options) {
+    const { message, choices } = options;
+    const numbered = choices
+        .map((choice, index) => ({ choice, index }))
+        .filter((e) => !e.choice.separator);
+    process.stdout.write(`\n${exports.style.bold(message)}\n`);
+    numbered.forEach((entry, position) => {
+        const hint = entry.choice.hint ? ` ${exports.style.grey(entry.choice.hint)}` : '';
+        process.stdout.write(`  ${position + 1}) ${entry.choice.label}${hint}\n`);
+    });
+    for (;;) {
+        const answer = (await question(`Choose 1-${numbered.length}: `)).trim();
+        if (answer === '')
+            continue;
+        const position = Number.parseInt(answer, 10);
+        if (Number.isInteger(position) && position >= 1 && position <= numbered.length) {
+            return numbered[position - 1].choice.value;
+        }
+        // Also accept an exact (case-insensitive) label so scripted input stays readable.
+        const byLabel = numbered.find((entry) => entry.choice.label.toLowerCase() === answer.toLowerCase());
+        if (byLabel)
+            return byLabel.choice.value;
+        process.stdout.write(exports.style.red('  Not a valid choice, try again.\n'));
+    }
+}
+/**
+ * A single readline interface is reused for line input when stdin is not a
+ * TTY. Creating one per prompt would work for a human typing, but a *piped*
+ * script has all its answers buffered at once: closing the interface after the
+ * first question discards every remaining line. Interactive sessions still get
+ * a throwaway interface per prompt so they can coexist with the raw-mode
+ * keypress handling in `select`.
+ */
+let sharedInterface = null;
+let stdinEnded = false;
+/** Lines that arrived before anything asked for them. */
+const bufferedLines = [];
+/** Callbacks waiting for the next line; `null` means stdin ended first. */
+const lineWaiters = [];
+function getSharedInterface() {
+    if (!sharedInterface) {
+        sharedInterface = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        // Queue every line as it arrives. Piped input delivers all of its lines
+        // immediately, long before the later prompts ask for them.
+        sharedInterface.on('line', (line) => {
+            const waiter = lineWaiters.shift();
+            if (waiter)
+                waiter(line);
+            else
+                bufferedLines.push(line);
+        });
+        sharedInterface.on('close', () => {
+            stdinEnded = true;
+            while (lineWaiters.length > 0)
+                lineWaiters.shift()?.(null);
+        });
+    }
+    return sharedInterface;
+}
+/** Release the shared interface so the process can exit. */
+function closePrompts() {
+    sharedInterface?.close();
+    sharedInterface = null;
+}
+/** Read a single line from stdin. */
+function question(prompt) {
+    if ((0, exports.isInteractive)()) {
+        return new Promise((resolve) => {
+            const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+            rl.question(prompt, (answer) => {
+                rl.close();
+                resolve(answer);
+            });
+        });
+    }
+    getSharedInterface();
+    process.stdout.write(prompt);
+    const buffered = bufferedLines.shift();
+    if (buffered !== undefined) {
+        process.stdout.write(`${buffered}\n`);
+        return Promise.resolve(buffered);
+    }
+    if (stdinEnded) {
+        // Input is exhausted - carrying on would spin forever re-asking.
+        process.stdout.write(`\n${exports.style.grey('Input ended.')}\n`);
+        process.exit(0);
+    }
+    return new Promise((resolve) => {
+        lineWaiters.push((line) => {
+            if (line === null) {
+                process.stdout.write(`\n${exports.style.grey('Input ended.')}\n`);
+                process.exit(0);
+            }
+            resolve(line);
+        });
+    });
+}
+/** Ask for free-text input, re-prompting until `validate` is happy. */
+async function text(options) {
+    const suffix = options.defaultValue ? exports.style.grey(` (${options.defaultValue})`) : '';
+    if (options.hint)
+        process.stdout.write(`${exports.style.grey(options.hint)}\n`);
+    for (;;) {
+        const raw = await question(`${exports.style.green('?')} ${exports.style.bold(options.message)}${suffix} `);
+        const value = raw.trim() === '' ? (options.defaultValue ?? '') : raw.trim();
+        if (value === '' && !options.allowEmpty && !options.defaultValue) {
+            process.stdout.write(exports.style.red('  A value is required.\n'));
+            continue;
+        }
+        const error = options.validate?.(value);
+        if (error) {
+            process.stdout.write(`${exports.style.red(`  ${error}`)}\n`);
+            continue;
+        }
+        return value;
+    }
+}
+/** Ask for multi-line input; a blank line ends the entry. */
+async function multilineText(message) {
+    process.stdout.write(`${exports.style.green('?')} ${exports.style.bold(message)}\n`);
+    process.stdout.write(exports.style.grey('  Finish with an empty line.\n'));
+    const lines = [];
+    for (;;) {
+        const line = await question('  ');
+        if (line.trim() === '')
+            break;
+        lines.push(line);
+    }
+    return lines.join('\n');
+}
+async function confirm(message, defaultValue = false) {
+    const hint = defaultValue ? 'Y/n' : 'y/N';
+    const answer = (await question(`${exports.style.green('?')} ${exports.style.bold(message)} ${exports.style.grey(`(${hint})`)} `))
+        .trim()
+        .toLowerCase();
+    if (answer === '')
+        return defaultValue;
+    return answer === 'y' || answer === 'yes';
+}
+/** Wait for the user before scrolling more output past them. */
+async function pause(message = 'Press enter to continue') {
+    await question(exports.style.grey(`${message} `));
+}
+function heading(text) {
+    process.stdout.write(`\n${exports.style.bold(exports.style.underline(text))}\n`);
+}
+function info(text) {
+    process.stdout.write(`${text}\n`);
+}
+function warn(text) {
+    process.stdout.write(`${exports.style.yellow('!')} ${text}\n`);
+}
+function error(text) {
+    process.stdout.write(`${exports.style.red('✖')} ${text}\n`);
+}
+function success(text) {
+    process.stdout.write(`${exports.style.green('✔')} ${text}\n`);
+}

package/dist/cjs/collection.js

@@ -1285,7 +1285,14 @@ class MongoLiteCollection {
             if (!upsert) {
                 return { acknowledged: true, matchedCount: 0, modifiedCount: 0, upsertedId: null };
             }
-            const result = await this.insertOne(replacement);
+            // An upsert adopts the `_id` the filter pinned down, matching MongoDB. Without
+            // this the inserted document gets a freshly generated id and the caller's
+            // `replaceOne({ _id }, ..., { upsert: true })` silently creates the wrong row.
+            const filterId = filter._id;
+            const seeded = typeof filterId === 'string'
+                ? { ...replacement, _id: filterId }
+                : replacement;
+            const result = await this.insertOne(seeded);
             return {
                 acknowledged: true,
                 matchedCount: 0,

package/dist/cjs/cursors/findCursor.js

@@ -779,6 +779,25 @@ class FindCursor {
      * @returns A promise that resolves to an array of documents.
      */
     async toArray() {
+        const { sql: finalSql, params: finalParams } = this.toSQL();
+        // Handle malformed json in the database
+        const rows = await this.db.all(finalSql, finalParams);
+        return rows.map((row) => {
+            const parsedData = safeJsonParse(row.data, `findCursor toArray for document ${row._id}`);
+            const restoredData = restoreDates(parsedData);
+            const doc = { _id: row._id, ...restoredData };
+            return this.applyProjection(doc);
+        });
+    }
+    /**
+     * Returns the SQL this cursor will execute, along with its bound parameters.
+     *
+     * Useful for debugging and for tools that want to show how a MongoDB-style
+     * filter was translated. Reflects any `sort`, `limit` and `skip` applied so
+     * far; `project` is applied in JavaScript after the rows come back and so
+     * does not appear here.
+     */
+    toSQL() {
         let finalSql = this.queryParts.sql;
         const finalParams = [...this.queryParts.params];
         if (this.sortCriteria) {
@@ -805,14 +824,7 @@ class FindCursor {
             finalSql += ` OFFSET ?`;
             finalParams.push(this.skipCount);
         }
-        // Handle malformed json in the database
-        const rows = await this.db.all(finalSql, finalParams);
-        return rows.map((row) => {
-            const parsedData = safeJsonParse(row.data, `findCursor toArray for document ${row._id}`);
-            const restoredData = restoreDates(parsedData);
-            const doc = { _id: row._id, ...restoredData };
-            return this.applyProjection(doc);
-        });
+        return { sql: finalSql, params: finalParams };
     }
     /**
      *  Executes the query and returns the first matching document.

package/dist/cjs/index.js

@@ -14,7 +14,7 @@ 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.NodeSqliteAdapter = exports.BrowserSqliteAdapter = exports.CloudflareDurableObjectAdapter = exports.ChangeStream = exports.MongoLiteCollection = void 0;
+exports.MongoLite = exports.projectToLocalShape = exports.isEmptyDiff = exports.applyDiff = exports.computeDiff = exports.buildWriteCommand = exports.SYNC_PROTOCOL_VERSION = exports.SyncRequestRejected = exports.HttpUpstreamSink = exports.MongoUpstreamSink = exports.SyncShadow = exports.SyncOutbox = exports.SyncReplicator = exports.NodeSqliteAdapter = exports.BrowserSqliteAdapter = exports.CloudflareDurableObjectAdapter = exports.ChangeStream = exports.MongoLiteCollection = void 0;
 const node_sqlite_js_1 = require("./adapters/node-sqlite.js");
 const mongo_client_js_1 = require("./mongo-client.js");
 var collection_js_1 = require("./collection.js");
@@ -28,6 +28,20 @@ var browser_js_1 = require("./adapters/browser.js");
 Object.defineProperty(exports, "BrowserSqliteAdapter", { enumerable: true, get: function () { return browser_js_1.BrowserSqliteAdapter; } });
 var node_sqlite_js_2 = require("./adapters/node-sqlite.js");
 Object.defineProperty(exports, "NodeSqliteAdapter", { enumerable: true, get: function () { return node_sqlite_js_2.NodeSqliteAdapter; } });
+const index_js_1 = require("./sync/index.js");
+var index_js_2 = require("./sync/index.js");
+Object.defineProperty(exports, "SyncReplicator", { enumerable: true, get: function () { return index_js_2.SyncReplicator; } });
+Object.defineProperty(exports, "SyncOutbox", { enumerable: true, get: function () { return index_js_2.SyncOutbox; } });
+Object.defineProperty(exports, "SyncShadow", { enumerable: true, get: function () { return index_js_2.SyncShadow; } });
+Object.defineProperty(exports, "MongoUpstreamSink", { enumerable: true, get: function () { return index_js_2.MongoUpstreamSink; } });
+Object.defineProperty(exports, "HttpUpstreamSink", { enumerable: true, get: function () { return index_js_2.HttpUpstreamSink; } });
+Object.defineProperty(exports, "SyncRequestRejected", { enumerable: true, get: function () { return index_js_2.SyncRequestRejected; } });
+Object.defineProperty(exports, "SYNC_PROTOCOL_VERSION", { enumerable: true, get: function () { return index_js_2.SYNC_PROTOCOL_VERSION; } });
+Object.defineProperty(exports, "buildWriteCommand", { enumerable: true, get: function () { return index_js_2.buildWriteCommand; } });
+Object.defineProperty(exports, "computeDiff", { enumerable: true, get: function () { return index_js_2.computeDiff; } });
+Object.defineProperty(exports, "applyDiff", { enumerable: true, get: function () { return index_js_2.applyDiff; } });
+Object.defineProperty(exports, "isEmptyDiff", { enumerable: true, get: function () { return index_js_2.isEmptyDiff; } });
+Object.defineProperty(exports, "projectToLocalShape", { enumerable: true, get: function () { return index_js_2.projectToLocalShape; } });
 /**
  * MongoLite class is the main entry point for interacting with the SQLite-backed database.
  *
@@ -61,5 +75,98 @@ class MongoLite extends mongo_client_js_1.MongoLite {
             super(new node_sqlite_js_1.NodeSqliteAdapter(dbPathOrOptions), options);
         }
     }
+    /**
+     * Replicates every insert, update and delete in this database to an upstream
+     * MongoDB deployment.
+     *
+     * Changes are captured by SQLite triggers into a durable outbox inside this
+     * database, in the same transaction as the write itself, then streamed
+     * upstream in batches. Replication survives process restarts and upstream
+     * outages: the outbox holds the backlog and a checkpoint records exactly how
+     * far it got.
+     *
+     * Requires the optional `mongodb` peer dependency.
+     *
+     * @example
+     * ```typescript
+     * const sync = client.syncToMongo({
+     *   connectionString: 'mongodb+srv://user:pass@cluster.example.com/app',
+     *   collections: ['users', 'orders'],
+     * });
+     *
+     * sync.on('error', (err) => console.error('replication degraded:', err));
+     * await sync.start();
+     *
+     * // …later, on shutdown
+     * await sync.stop({ flush: true });
+     * ```
+     */
+    syncToMongo(options) {
+        const { connectionString, database, writeConcern, driverOptions, driver, authSource, authMechanism, authMechanismProperties, username, password, tls, tlsCAFile, tlsCertificateKeyFile, tlsCertificateKeyFilePassword, tlsCRLFile, tlsAllowInvalidHostnames, tlsAllowInvalidCertificates, ...syncOptions } = options;
+        const sink = new index_js_1.MongoUpstreamSink({
+            connectionString,
+            database,
+            writeConcern,
+            driverOptions,
+            driver,
+            authSource,
+            authMechanism,
+            authMechanismProperties,
+            username,
+            password,
+            tls,
+            tlsCAFile,
+            tlsCertificateKeyFile,
+            tlsCertificateKeyFilePassword,
+            tlsCRLFile,
+            tlsAllowInvalidHostnames,
+            tlsAllowInvalidCertificates,
+            idMapping: syncOptions.idMapping,
+            // The sink builds the conditional writes, so it needs the same answer the
+            // replicator uses when deciding whether to track shadows at all.
+            versioning: syncOptions.versioning,
+        });
+        return this.createSync(sink, syncOptions);
+    }
+    /**
+     * Replicates changes to a remote HTTP API, which applies them to MongoDB on this
+     * client's behalf. For deployments where the local instance cannot reach the database
+     * directly.
+     *
+     * The wire format carries MongoDB-shaped commands along with the version predicates,
+     * so replication behaves the same as over a direct connection — the upstream stays the
+     * source of truth and concurrent writers are still detected. Mount
+     * `@semics-tech/mongolite/server` on the API to receive the messages.
+     *
+     * @example
+     * ```typescript
+     * const sync = client.syncToHttp({
+     *   baseUrl: 'https://api.example.com',
+     *   database: 'app',
+     *   headers: { 'luna-environment': 'prod' },
+     *   getAuthHeaders: async () => ({ Authorization: `Bearer ${await getAccessToken()}` }),
+     * });
+     *
+     * await sync.start();
+     * ```
+     */
+    syncToHttp(options) {
+        const { baseUrl, database, pathPrefix, getAuthHeaders, headers, cookies, fetch: fetchImpl, timeoutMs, includeCommands, ...syncOptions } = options;
+        const sink = new index_js_1.HttpUpstreamSink({
+            baseUrl,
+            database,
+            pathPrefix,
+            getAuthHeaders,
+            headers,
+            cookies,
+            fetch: fetchImpl,
+            timeoutMs,
+            includeCommands,
+            idMapping: syncOptions.idMapping,
+            versioning: syncOptions.versioning,
+            replicator: syncOptions.name,
+        });
+        return this.createSync(sink, syncOptions);
+    }
 }
 exports.MongoLite = MongoLite;

package/dist/cjs/mongo-client.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MongoLite = void 0;
 const collection_js_1 = require("./collection.js");
+const replicator_js_1 = require("./sync/replicator.js");
 /**
  * Core MongoLite client. Accepts any `IDatabaseAdapter` implementation.
  *
@@ -42,11 +43,27 @@ class MongoLite {
     listCollections() {
         return {
             toArray: async () => {
-                const result = await this.db.all(`SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'`);
+                // `__mongolite*` tables are internal bookkeeping (change log, sync
+                // outbox and checkpoints), not user collections.
+                const result = await this.db.all(`SELECT name FROM sqlite_master
+           WHERE type='table' AND name NOT LIKE 'sqlite_%' AND name NOT LIKE '__mongolite%'`);
                 return result.map((row) => row.name);
             },
         };
     }
+    /**
+     * Starts replicating this database's changes to an upstream {@link SyncSink}.
+     *
+     * Node.js users replicating to MongoDB should prefer the `syncToMongo`
+     * overload on the package-root `MongoLite`, which takes a connection string
+     * directly. This method is the backend-agnostic form — pass any sink to
+     * replicate over HTTP, into a queue, or to a test double.
+     *
+     * The returned replicator is **not** started; call `start()` on it.
+     */
+    createSync(sink, options = {}) {
+        return new replicator_js_1.SyncReplicator(this.db, sink, { verbose: this.options.verbose, ...options });
+    }
     /**
      * Returns a typed collection handle.
      * @param name The collection (table) name.