@semics-tech/mongolite 1.3.0 → 1.4.1

package/README.md

@@ -12,6 +12,7 @@ A MongoDB-like client backed by SQLite. Use a familiar MongoDB API with the simp
 - 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
+- You want a persistent, high-performance local cache in front of a remote MongoDB, one that survives restarts and network interruptions, without giving up Mongo's query semantics (including things that are natural in a document model but awkward in SQL, like layered/override queries)
 
 ## Features
 
@@ -24,6 +25,8 @@ A MongoDB-like client backed by SQLite. Use a familiar MongoDB API with the simp
 - **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()`
+- **MongoDB sync** — replicate local writes upstream, surviving restarts and offline periods
+- **HTTP sync** — post the same changes to a remote API when MongoDB is unreachable
 - **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
 
@@ -83,28 +86,29 @@ raw SQL are a menu item away when you want them. See [the CLI docs](./docs/CLI.m
 
 ## 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   | 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 |
-| [CLI](./docs/CLI.md) | `npx mongolite` — guided explorer for browsing and querying a database |
-| [Query Debugger](./docs/DEBUGGER.md) | The older command-driven REPL (`npx mongolite --repl`) |
-| [Benchmarks](./docs/BENCHMARKS.md) | Performance benchmarks and storage characteristics |
-| [Cloudflare Durable Objects](./docs/CLOUDFLARE.md) | Using MongoLite inside a Cloudflare Durable Object |
+| 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()`                    |
+| [Syncing to MongoDB](./docs/SYNC.md)               | Replication to an upstream MongoDB, directly or through an HTTP API    |
+| [JSON Safety](./docs/JSON_SAFETY.md)               | Document validation and corrupted data recovery                        |
+| [CLI](./docs/CLI.md)                               | `npx mongolite` — guided explorer for browsing and querying a database |
+| [Query Debugger](./docs/DEBUGGER.md)               | The older command-driven REPL (`npx mongolite --repl`)                 |
+| [Benchmarks](./docs/BENCHMARKS.md)                 | Performance benchmarks and storage characteristics                     |
+| [Cloudflare Durable Objects](./docs/CLOUDFLARE.md) | Using MongoLite inside a Cloudflare Durable Object                     |
 
 ## Backend Examples
 
@@ -125,9 +129,9 @@ await client.close();
 ```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
+  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,
 });
@@ -149,7 +153,7 @@ 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
+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.
 
@@ -193,6 +197,7 @@ 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
@@ -248,6 +253,60 @@ export class MyDurableObject extends DurableObject {
 
 > See [docs/CLOUDFLARE.md](./docs/CLOUDFLARE.md) for the full guide, supported operations, and limitations.
 
+## Syncing to MongoDB
+
+Point MongoLite at an upstream MongoDB deployment and every insert, update and
+delete is replicated to it. The local database becomes a local-first write layer
+that converges upstream — through restarts, network outages and offline periods.
+
+Requires the optional `mongodb` peer dependency (`npm install mongodb`).
+
+```typescript
+const client = new MongoLite('./app.sqlite');
+await client.connect();
+
+const sync = client.syncToMongo({
+  connectionString: 'mongodb+srv://user:pass@cluster.example.com/app',
+  collections: ['users', 'orders'], // Omit to replicate everything
+});
+
+await sync.start();
+
+// Ordinary writes — replication happens in the background.
+await client.collection('users').insertOne({ name: 'Alice', age: 30 });
+
+await sync.stop({ flush: true }); // Push anything still queued on shutdown
+```
+
+Changes are captured by SQLite triggers into a durable outbox **inside the same
+transaction as the write itself**, so a change is either committed locally _and_
+queued for replication, or neither. A background worker coalesces the queue, applies
+it upstream, and only then advances a persisted checkpoint — so an outage parks the
+backlog rather than losing it, and a restart resumes exactly where it stopped.
+
+Upstream is treated as the source of truth. Each push is a conditional write against
+the version it last saw, and carries only the fields that actually changed, so a
+concurrent edit by another writer is detected rather than silently overwritten.
+
+Where the local instance cannot reach MongoDB directly, `syncToHttp` posts the same
+operations to a remote API instead, and `@semics-tech/mongolite/server` applies them on
+the far side:
+
+```typescript
+const sync = client.syncToHttp({
+  baseUrl: 'https://api.example.com',
+  database: 'app',
+  getAuthHeaders: async () => ({ Authorization: `Bearer ${await getAccessToken()}` }),
+});
+```
+
+The version predicates travel with each operation and conflicts come back in the
+response, so the HTTP hop is pure transport — replication behaves the same either way.
+
+> See [docs/SYNC.md](./docs/SYNC.md) for the full guide: syncing through an HTTP API,
+> advanced authentication (X.509, mTLS, AWS IAM, Azure managed identity), filtering and
+> reshaping documents, dead-letter handling, multiple upstreams, and custom sinks.
+
 ## Development
 
 ```bash

package/dist/cjs/collection.js

@@ -1099,11 +1099,7 @@ class MongoLiteCollection {
      */
     async countDocuments(filter = {}) {
         await this.ensureTable();
-        const paramsForCount = [];
-        const whereClause = new findCursor_js_1.FindCursor(this.db, this.name, filter)['buildGuardedWhereClause'](filter, paramsForCount);
-        const countSql = `SELECT COUNT(*) as count FROM "${this.name}" WHERE ${whereClause}`;
-        const result = await this.db.get(countSql, paramsForCount);
-        return result?.count || 0;
+        return this.find(filter).count();
     }
     /**
      * Finds rows whose stored `data` column is not valid JSON.
@@ -1285,7 +1281,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

@@ -123,15 +123,16 @@ function restoreDates(obj) {
  * Represents a cursor for find operations, allowing chaining of limit, skip, and sort.
  */
 class FindCursor {
-    constructor(db, collectionName, initialFilter, options = {}) {
+    constructor(db, collectionName, filter, options = {}) {
         this.db = db;
         this.collectionName = collectionName;
+        this.filter = filter;
         this.options = options;
         this.limitCount = null;
         this.skipCount = null;
         this.sortCriteria = null;
         this.projectionFields = null;
-        this.queryParts = this.buildSelectQuery(initialFilter);
+        this.queryParts = this.buildSelectQuery(filter);
     }
     parseJsonPath(path) {
         return `'$.${path.replace(/\./g, '.')}'`;
@@ -840,9 +841,10 @@ class FindCursor {
      * @returns A promise that resolves to the count of matching documents.
      */
     async count() {
-        const whereClause = this.buildWhereClause({}, []);
+        const params = [];
+        const whereClause = this.buildGuardedWhereClause(this.filter, params);
         const countSql = `SELECT COUNT(*) as count FROM "${this.collectionName}" WHERE ${whereClause}`;
-        const result = await this.db.get(countSql);
+        const result = await this.db.get(countSql, params);
         return result?.count ?? 0; // Return 0 if result is undefined
     }
 }

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.

package/dist/cjs/server.js

@@ -0,0 +1,164 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SyncReceiver = exports.SyncProtocolError = exports.SYNC_PROTOCOL_VERSION = void 0;
+exports.createSyncReceiver = createSyncReceiver;
+/**
+ * Server-side entry point: receives sync messages from a MongoLite client and applies
+ * them to MongoDB.
+ *
+ * Install this on the API that sits in front of your database, for deployments where
+ * the local instance cannot reach MongoDB directly.
+ *
+ * ```ts
+ * import { MongoClient } from 'mongodb';
+ * import { createSyncReceiver } from '@semics-tech/mongolite/server';
+ *
+ * const mongo = await new MongoClient(process.env.MONGO_URL!).connect();
+ * const receiver = createSyncReceiver({
+ *   client: mongo,
+ *   database: 'app',
+ *   allowedCollections: ['users', 'orders'],
+ * });
+ *
+ * app.post('/sync/app/_sync', async (req, res) => {
+ *   const result = await receiver.apply(req.body);
+ *   res.status(result.status).type('application/json').send(result.body);
+ * });
+ * ```
+ *
+ * This module imports nothing SQLite-related, so it is safe to install on a server that
+ * has no local database of its own.
+ */
+const commands_js_1 = require("./sync/commands.js");
+const mongoExecutor_js_1 = require("./sync/mongoExecutor.js");
+const protocol_js_1 = require("./sync/protocol.js");
+var protocol_js_2 = require("./sync/protocol.js");
+Object.defineProperty(exports, "SYNC_PROTOCOL_VERSION", { enumerable: true, get: function () { return protocol_js_2.SYNC_PROTOCOL_VERSION; } });
+Object.defineProperty(exports, "SyncProtocolError", { enumerable: true, get: function () { return protocol_js_2.SyncProtocolError; } });
+const JSON_HEADERS = { 'content-type': 'application/json' };
+class SyncReceiver {
+    constructor(options) {
+        this.options = options;
+        if (!options.client)
+            throw new Error('createSyncReceiver requires a connected `client`.');
+        this.db = options.client.db(options.database);
+    }
+    /**
+     * Applies a batch of operations.
+     *
+     * @param body The raw request body — a string, or an already-parsed object.
+     * @returns Status and Extended JSON body to send back.
+     */
+    async apply(body) {
+        try {
+            const decoded = (0, protocol_js_1.decodeBody)(body);
+            const { replicator, operations } = (0, protocol_js_1.parseApplyRequest)(decoded);
+            const maxOperations = this.options.maxOperations ?? 1000;
+            if (operations.length > maxOperations) {
+                throw new protocol_js_1.SyncProtocolError(`Batch of ${operations.length} exceeds the limit of ${maxOperations}`, 413);
+            }
+            const collections = [...new Set(operations.map((op) => op.collection))];
+            this.assertCollectionsAllowed(collections);
+            await this.authorise({ replicator, collections, operationCount: operations.length });
+            const writes = operations.map((op, index) => ({
+                index,
+                op,
+                command: this.commandFor(op, decoded, index),
+            }));
+            const result = await (0, mongoExecutor_js_1.executeWrites)(this.db, writes, {
+                writeConcern: this.options.writeConcern ?? { w: 'majority' },
+                versioning: this.options.versioning ?? true,
+                idMapping: this.options.idMapping,
+                ObjectId: this.options.ObjectId,
+            });
+            return this.ok({
+                protocol: protocol_js_1.SYNC_PROTOCOL_VERSION,
+                applied: result.applied,
+                failures: result.failures,
+                conflicts: result.conflicts,
+            });
+        }
+        catch (err) {
+            return this.error(err);
+        }
+    }
+    /** Reads documents back by `_id`, so a client can refresh its shadow after a conflict. */
+    async fetch(body) {
+        try {
+            const { collection, documentIds } = (0, protocol_js_1.parseFetchRequest)((0, protocol_js_1.decodeBody)(body));
+            this.assertCollectionsAllowed([collection]);
+            await this.authorise({
+                replicator: 'fetch',
+                collections: [collection],
+                operationCount: documentIds.length,
+            });
+            const documents = await (0, mongoExecutor_js_1.fetchDocuments)(this.db, collection, documentIds, this.options.idMapping, this.options.ObjectId);
+            return this.ok({ protocol: protocol_js_1.SYNC_PROTOCOL_VERSION, documents });
+        }
+        catch (err) {
+            return this.error(err);
+        }
+    }
+    // ---------------------------------------------------------------- internals
+    /**
+     * Produces the command to execute for an operation.
+     *
+     * By default this **rebuilds** the command from the operation's own fields rather than
+     * using whatever the client sent. For a well-behaved client the two are identical;
+     * for a hostile one the difference is the whole security boundary.
+     */
+    commandFor(op, decoded, index) {
+        if (this.options.trustClientCommands) {
+            const wire = decoded.operations?.[index];
+            const command = wire?.command;
+            if (command && typeof command === 'object')
+                return command;
+        }
+        return (0, commands_js_1.buildWriteCommand)(op, {
+            idMapping: this.options.idMapping,
+            versioning: this.options.versioning ?? true,
+            ObjectId: this.options.ObjectId,
+        });
+    }
+    assertCollectionsAllowed(collections) {
+        const allowed = this.options.allowedCollections;
+        if (!allowed)
+            return;
+        const permitted = new Set(allowed);
+        for (const collection of collections) {
+            if (!permitted.has(collection)) {
+                throw new protocol_js_1.SyncProtocolError(`Collection "${collection}" is not permitted`, 403);
+            }
+        }
+    }
+    async authorise(context) {
+        if (!this.options.verifyRequest)
+            return;
+        const verdict = await this.options.verifyRequest(context);
+        if (verdict === false) {
+            throw new protocol_js_1.SyncProtocolError('Request rejected', 403);
+        }
+    }
+    ok(payload) {
+        return { status: 200, body: (0, protocol_js_1.encodeBody)(payload), headers: JSON_HEADERS };
+    }
+    error(err) {
+        const status = err instanceof protocol_js_1.SyncProtocolError ? err.status : 500;
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            status,
+            // 5xx bodies stay vague: an unexpected error can carry connection strings or
+            // document contents, and this response goes to a client.
+            body: (0, protocol_js_1.encodeBody)({
+                protocol: protocol_js_1.SYNC_PROTOCOL_VERSION,
+                error: status >= 500 ? 'Internal error applying sync batch' : message,
+            }),
+            headers: JSON_HEADERS,
+        };
+    }
+}
+exports.SyncReceiver = SyncReceiver;
+/** Creates a receiver for sync messages posted by a MongoLite client. */
+function createSyncReceiver(options) {
+    return new SyncReceiver(options);
+}