@semics-tech/mongolite 1.3.0 → 1.4.1

package/dist/cjs/sync/commands.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UPDATED_AT_FIELD = exports.VERSION_FIELD = void 0;
+exports.isConditional = isConditional;
+exports.isReservedPath = isReservedPath;
+exports.stripReservedFields = stripReservedFields;
+exports.readVersion = readVersion;
+exports.toUpstreamId = toUpstreamId;
+exports.buildWriteCommand = buildWriteCommand;
+/**
+ * Builds the MongoDB write commands that realise a {@link SyncOperation}.
+ *
+ * This lives on its own because three places must agree on it byte for byte: the
+ * direct MongoDB sink, the HTTP sink that ships commands to a remote API, and the
+ * receiver on the far side that applies them. If any of the three built its own
+ * commands they would drift, and the drift would show up as data loss rather than as a
+ * test failure.
+ */
+const bson_1 = require("bson");
+/** Field carrying the optimistic-concurrency version on upstream documents. */
+exports.VERSION_FIELD = '_v';
+/** Field carrying the server-stamped last-write time on upstream documents. */
+exports.UPDATED_AT_FIELD = '_updatedAt';
+/** True when this operation asserts a specific upstream revision. */
+function isConditional(op) {
+    return op.baseVersion !== null && op.baseVersion !== undefined;
+}
+/** `_id` is the identity; `_v`/`_updatedAt` are managed by the update itself. */
+function isReservedPath(path) {
+    const root = path.split('.')[0];
+    return root === '_id' || root === exports.VERSION_FIELD || root === exports.UPDATED_AT_FIELD;
+}
+function stripReservedFields(value) {
+    return Object.fromEntries(Object.entries(value).filter(([key]) => !isReservedPath(key)));
+}
+/** Reads `_v` off an upstream document, tolerating its absence. */
+function readVersion(document) {
+    if (!document)
+        return null;
+    const raw = document[exports.VERSION_FIELD];
+    return typeof raw === 'number' ? raw : null;
+}
+/**
+ * MongoLite stores `_id` as a string. Converting ObjectId-shaped ids back to real
+ * `ObjectId`s keeps replicated documents indistinguishable from ones written by a
+ * native MongoDB client.
+ */
+function toUpstreamId(documentId, idMapping = 'auto', ObjectId = bson_1.ObjectId) {
+    if (idMapping === 'string')
+        return documentId;
+    try {
+        return ObjectId.isValid(documentId) && /^[0-9a-fA-F]{24}$/.test(documentId)
+            ? new ObjectId(documentId)
+            : documentId;
+    }
+    catch {
+        return documentId;
+    }
+}
+/**
+ * Builds the upstream write for one operation.
+ *
+ * Every form is idempotent by `_id`, which is what makes at-least-once delivery safe:
+ * replaying a batch reproduces the same upstream state.
+ *
+ * With versioning on, writes are additionally *conditional* on the document still being
+ * at the version we last saw. That is the difference between "my change is newer, so it
+ * wins" — which cannot detect a lost update — and "I am replacing exactly the revision
+ * I read", which can.
+ */
+function buildWriteCommand(op, options = {}) {
+    const { idMapping = 'auto', versioning = true, ObjectId } = options;
+    const _id = toUpstreamId(op.documentId, idMapping, ObjectId);
+    if (op.type === 'delete') {
+        const filter = isConditional(op) ? { _id, [exports.VERSION_FIELD]: op.baseVersion } : { _id };
+        return { deleteOne: { filter } };
+    }
+    if (!versioning) {
+        // The local database is treated as authoritative: replace wholesale, so a field
+        // deleted locally disappears upstream too.
+        return {
+            replaceOne: { filter: { _id }, replacement: { ...(op.document ?? {}), _id }, upsert: true },
+        };
+    }
+    // Never been upstream: create it, and let a duplicate key tell us we lost the race to
+    // create. `$setOnInsert` alone means an existing document is left untouched.
+    if (!isConditional(op)) {
+        const document = stripReservedFields(op.document ?? {});
+        return {
+            updateOne: {
+                filter: { _id },
+                update: {
+                    $setOnInsert: { ...document, [exports.VERSION_FIELD]: 1 },
+                    $currentDate: { [exports.UPDATED_AT_FIELD]: true },
+                },
+                upsert: true,
+            },
+        };
+    }
+    // Known revision: apply only what changed, conditional on that revision.
+    const update = {
+        $inc: { [exports.VERSION_FIELD]: 1 },
+        $currentDate: { [exports.UPDATED_AT_FIELD]: true },
+    };
+    const diff = op.diff;
+    if (diff) {
+        const set = stripReservedFields(diff.set);
+        const unset = diff.unset.filter((path) => !isReservedPath(path));
+        if (Object.keys(set).length > 0)
+            update.$set = set;
+        if (unset.length > 0) {
+            update.$unset = Object.fromEntries(unset.map((path) => [path, '']));
+        }
+    }
+    else {
+        // No shadow to diff against — fall back to writing the whole document, minus the
+        // bookkeeping fields the update itself manages.
+        update.$set = stripReservedFields(op.document ?? {});
+    }
+    return {
+        updateOne: {
+            filter: { _id, [exports.VERSION_FIELD]: op.baseVersion },
+            update,
+        },
+    };
+}

package/dist/cjs/sync/diff.js

@@ -0,0 +1,174 @@
+"use strict";
+/**
+ * Field-level diffing between the last-known server state and the local document.
+ *
+ * Replication used to push whole documents, which meant a local edit to one field
+ * rewrote every other field too — including fields another writer had just changed,
+ * and including fields whose BSON type the local store cannot represent. Diffing
+ * narrows each push to `$set`/`$unset` of what genuinely changed, so everything else
+ * upstream is left exactly as it was.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deepEqual = deepEqual;
+exports.computeDiff = computeDiff;
+exports.isEmptyDiff = isEmptyDiff;
+exports.applyDiff = applyDiff;
+/**
+ * True when `value` is a genuine plain object worth recursing into.
+ *
+ * Class instances are deliberately excluded. A `Date`, `ObjectId` or `Binary` is
+ * `typeof 'object'`, and treating one as a bag of fields would copy it into a plain
+ * object — destroying exactly the BSON types the shadow exists to preserve.
+ */
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * Structural equality, insensitive to key order.
+ *
+ * `JSON.stringify` comparison would report `{a:1,b:2}` and `{b:2,a:1}` as different and
+ * push a spurious update on every sync.
+ */
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    // NaN is the one primitive that isn't equal to itself.
+    if (typeof a === 'number' && typeof b === 'number')
+        return Number.isNaN(a) && Number.isNaN(b);
+    // Two equal instants are separate objects; without this every sync would rewrite
+    // any date-valued field.
+    if (a instanceof Date || b instanceof Date) {
+        return a instanceof Date && b instanceof Date && a.getTime() === b.getTime();
+    }
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((item, index) => deepEqual(item, b[index]));
+    }
+    if (isPlainObject(a) && isPlainObject(b)) {
+        const aKeys = Object.keys(a);
+        const bKeys = Object.keys(b);
+        if (aKeys.length !== bKeys.length)
+            return false;
+        return aKeys.every((key) => Object.prototype.hasOwnProperty.call(b, key) && deepEqual(a[key], b[key]));
+    }
+    return false;
+}
+/**
+ * Computes the minimal update that turns `base` into `local`.
+ *
+ * `base` must be the **lossy JSON projection** of the server document — the same shape
+ * the local store would have produced for it (see `projectToLocalShape` in `shadow.ts`).
+ * That is what makes type preservation work: a server `Date` projects to the same ISO
+ * string the local store holds, compares equal, and so never appears in the diff — the
+ * upstream `Date` survives untouched.
+ *
+ * Nested objects recurse into dotted paths, so two writers editing different sub-fields
+ * of the same document do not collide.
+ *
+ * **Arrays are atomic.** Any change to an array replaces the whole array. Positional
+ * diffing of arrays is famously error-prone once elements are inserted or reordered, and
+ * a wrong answer here silently corrupts data — so this deliberately does not attempt it.
+ *
+ * @param base The last-known server state, projected to local shape. `null` if the
+ * document has never been upstream, in which case every field is new.
+ * @param local The current local document.
+ */
+function computeDiff(base, local) {
+    const diff = { set: {}, unset: [] };
+    collect(base ?? {}, local, '', diff);
+    return diff;
+}
+function collect(base, local, prefix, diff) {
+    const keys = new Set([...Object.keys(base), ...Object.keys(local)]);
+    for (const key of keys) {
+        // `_id` is the identity, never part of the update.
+        if (prefix === '' && key === '_id')
+            continue;
+        const path = prefix === '' ? key : `${prefix}.${key}`;
+        const inLocal = Object.prototype.hasOwnProperty.call(local, key);
+        const inBase = Object.prototype.hasOwnProperty.call(base, key);
+        if (!inLocal) {
+            diff.unset.push(path);
+            continue;
+        }
+        const localValue = local[key];
+        const baseValue = base[key];
+        if (!inBase) {
+            diff.set[path] = localValue;
+            continue;
+        }
+        // Recurse only when both sides are objects; otherwise the shapes differ and the
+        // whole subtree is replaced.
+        if (isPlainObject(baseValue) && isPlainObject(localValue)) {
+            collect(baseValue, localValue, path, diff);
+            continue;
+        }
+        if (!deepEqual(baseValue, localValue)) {
+            diff.set[path] = localValue;
+        }
+    }
+}
+/** True when the diff would change nothing upstream. */
+function isEmptyDiff(diff) {
+    return Object.keys(diff.set).length === 0 && diff.unset.length === 0;
+}
+/**
+ * Applies a diff to a copy of `document`, mirroring what the upstream `$set`/`$unset`
+ * does.
+ *
+ * Used to roll the shadow forward after a successful push without a second round trip.
+ * Because it edits the *server* document in place, fields the diff never mentions keep
+ * their original BSON values — which is the whole point of diffing in the first place.
+ */
+function applyDiff(document, diff) {
+    const result = clone(document);
+    for (const [path, value] of Object.entries(diff.set)) {
+        setPath(result, path.split('.'), value);
+    }
+    for (const path of diff.unset) {
+        unsetPath(result, path.split('.'));
+    }
+    return result;
+}
+/**
+ * Structured clone that leaves class instances (BSON `Date`, `ObjectId`, `Binary`, …)
+ * by reference. Copying them field-by-field would destroy exactly the types the shadow
+ * exists to preserve.
+ */
+function clone(value) {
+    if (Array.isArray(value))
+        return value.map(clone);
+    if (isPlainObject(value)) {
+        const out = {};
+        for (const [key, item] of Object.entries(value))
+            out[key] = clone(item);
+        return out;
+    }
+    return value;
+}
+function setPath(target, segments, value) {
+    const [head, ...rest] = segments;
+    if (rest.length === 0) {
+        target[head] = value;
+        return;
+    }
+    const next = target[head];
+    // Mirror MongoDB: a dotted path creates intermediate objects as needed.
+    const container = isPlainObject(next) ? next : {};
+    target[head] = container;
+    setPath(container, rest, value);
+}
+function unsetPath(target, segments) {
+    const [head, ...rest] = segments;
+    if (rest.length === 0) {
+        delete target[head];
+        return;
+    }
+    const next = target[head];
+    if (isPlainObject(next))
+        unsetPath(next, rest);
+}

package/dist/cjs/sync/httpSink.js

@@ -0,0 +1,159 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SyncRequestRejected = exports.HttpUpstreamSink = void 0;
+/**
+ * A {@link SyncSink} that ships changes to a remote HTTP API instead of connecting to
+ * MongoDB directly, for deployments where the local instance cannot reach the database.
+ *
+ * The API receives MongoDB-shaped commands and applies them on the client's behalf —
+ * see `@semics-tech/mongolite/server` for a receiver that does exactly that.
+ *
+ * Version predicates travel with each operation and conflicts come back in the response,
+ * so replication behaves the same over HTTP as it does over a direct connection: the
+ * upstream stays the source of truth, and a concurrent writer is detected rather than
+ * overwritten.
+ */
+const commands_js_1 = require("./commands.js");
+const protocol_js_1 = require("./protocol.js");
+class HttpUpstreamSink {
+    constructor(options) {
+        this.options = options;
+        this.name = 'http';
+        this.cookie = null;
+        if (!options.baseUrl)
+            throw new Error('HttpUpstreamSink requires a `baseUrl`.');
+        if (!options.database)
+            throw new Error('HttpUpstreamSink requires a `database`.');
+        const globalFetch = globalThis.fetch;
+        if (!options.fetch && typeof globalFetch !== 'function') {
+            throw new Error('HttpUpstreamSink needs a `fetch` implementation. Node 18+ provides one globally; ' +
+                'on older runtimes pass `fetch` explicitly.');
+        }
+        this.fetchImpl = options.fetch ?? globalFetch;
+        this.idMapping = options.idMapping ?? 'auto';
+        this.versioning = options.versioning ?? true;
+    }
+    async apply(operations) {
+        const includeCommands = this.options.includeCommands ?? true;
+        const request = {
+            protocol: protocol_js_1.SYNC_PROTOCOL_VERSION,
+            replicator: this.options.replicator,
+            operations: operations.map((op) => (0, protocol_js_1.toWireOperation)(op, includeCommands
+                ? (0, commands_js_1.buildWriteCommand)(op, { idMapping: this.idMapping, versioning: this.versioning })
+                : undefined)),
+        };
+        let response;
+        try {
+            response = await this.send('_sync', request);
+        }
+        catch (err) {
+            // A request the API rejects outright will be rejected again on every retry, so
+            // it is reported as a per-operation failure — dead-lettered, not spun on. The
+            // sink's contract is that throwing means "transient", and this is not that.
+            if (err instanceof SyncRequestRejected) {
+                return {
+                    applied: 0,
+                    failures: operations.map((_op, index) => ({
+                        index,
+                        message: err.message,
+                        code: err.status,
+                    })),
+                };
+            }
+            throw err;
+        }
+        return {
+            applied: response.applied ?? 0,
+            failures: response.failures,
+            conflicts: response.conflicts,
+        };
+    }
+    async fetch(collection, documentIds) {
+        if (documentIds.length === 0)
+            return [];
+        const response = await this.send('_sync/fetch', {
+            protocol: protocol_js_1.SYNC_PROTOCOL_VERSION,
+            collection,
+            documentIds,
+        });
+        return response.documents ?? [];
+    }
+    // ---------------------------------------------------------------- internals
+    endpoint(path) {
+        const base = this.options.baseUrl.replace(/\/+$/, '');
+        const prefix = (this.options.pathPrefix ?? 'sync').replace(/^\/+|\/+$/g, '');
+        return `${base}/${prefix}/${encodeURIComponent(this.options.database)}/${path}`;
+    }
+    async requestHeaders() {
+        const headers = {
+            'content-type': protocol_js_1.SYNC_CONTENT_TYPE,
+            accept: protocol_js_1.SYNC_CONTENT_TYPE,
+            ...this.options.headers,
+            ...(this.options.getAuthHeaders ? await this.options.getAuthHeaders() : {}),
+        };
+        if (this.cookie && (this.options.cookies ?? true))
+            headers.cookie = this.cookie;
+        return headers;
+    }
+    /**
+     * Posts a body and decodes the reply.
+     *
+     * Retries are deliberately *not* handled here — the replicator already owns backoff,
+     * outage buffering and checkpointing. This throws on anything retryable and lets it do
+     * its job; throwing twice over would compound the delays.
+     */
+    async send(path, body) {
+        const timeoutMs = this.options.timeoutMs ?? 30000;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        let response;
+        try {
+            response = await this.fetchImpl(this.endpoint(path), {
+                method: 'POST',
+                headers: await this.requestHeaders(),
+                body: (0, protocol_js_1.encodeBody)(body),
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            // Network failure, DNS, timeout — all transient as far as we can tell.
+            throw new Error(`Sync request to ${this.endpoint(path)} failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (this.options.cookies ?? true) {
+            const setCookie = response.headers.get('set-cookie');
+            if (setCookie)
+                this.cookie = setCookie;
+        }
+        const text = await response.text();
+        if (!response.ok) {
+            const detail = text.slice(0, 500);
+            // 4xx means the request itself is wrong and will stay wrong; throwing would spin
+            // forever. Surfacing it as a per-operation failure dead-letters the batch instead.
+            // 408 and 429 are the exceptions — they explicitly invite a retry.
+            const retryable = response.status >= 500 || response.status === 408 || response.status === 429;
+            if (retryable) {
+                throw new Error(`Sync request failed with ${response.status}: ${detail}`);
+            }
+            throw new SyncRequestRejected(`Sync request rejected with ${response.status}: ${detail}`, response.status);
+        }
+        return (0, protocol_js_1.decodeBody)(text);
+    }
+}
+exports.HttpUpstreamSink = HttpUpstreamSink;
+/**
+ * The remote API refused the request outright.
+ *
+ * Distinct from a transport failure: retrying will produce the same refusal, so the
+ * batch is dead-lettered rather than retried.
+ */
+class SyncRequestRejected extends Error {
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = 'SyncRequestRejected';
+    }
+}
+exports.SyncRequestRejected = SyncRequestRejected;

package/dist/cjs/sync/index.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deepEqual = exports.isEmptyDiff = exports.applyDiff = exports.computeDiff = exports.projectToLocalShape = exports.SHADOW_TABLE = exports.SyncShadow = exports.fromWireOperation = exports.toWireOperation = exports.decodeBody = exports.encodeBody = exports.SyncProtocolError = exports.SYNC_PROTOCOL_VERSION = exports.fetchDocuments = exports.executeWrites = exports.toUpstreamId = exports.buildWriteCommand = exports.SyncRequestRejected = exports.HttpUpstreamSink = exports.UPDATED_AT_FIELD = exports.VERSION_FIELD = exports.MongoUpstreamSink = exports.SYNC_OBJECT_PREFIX = exports.DEAD_LETTER_TABLE = exports.STATE_TABLE = exports.OUTBOX_TABLE = exports.SyncOutbox = exports.SyncReplicator = void 0;
+var replicator_js_1 = require("./replicator.js");
+Object.defineProperty(exports, "SyncReplicator", { enumerable: true, get: function () { return replicator_js_1.SyncReplicator; } });
+var outbox_js_1 = require("./outbox.js");
+Object.defineProperty(exports, "SyncOutbox", { enumerable: true, get: function () { return outbox_js_1.SyncOutbox; } });
+Object.defineProperty(exports, "OUTBOX_TABLE", { enumerable: true, get: function () { return outbox_js_1.OUTBOX_TABLE; } });
+Object.defineProperty(exports, "STATE_TABLE", { enumerable: true, get: function () { return outbox_js_1.STATE_TABLE; } });
+Object.defineProperty(exports, "DEAD_LETTER_TABLE", { enumerable: true, get: function () { return outbox_js_1.DEAD_LETTER_TABLE; } });
+Object.defineProperty(exports, "SYNC_OBJECT_PREFIX", { enumerable: true, get: function () { return outbox_js_1.SYNC_OBJECT_PREFIX; } });
+var mongoSink_js_1 = require("./mongoSink.js");
+Object.defineProperty(exports, "MongoUpstreamSink", { enumerable: true, get: function () { return mongoSink_js_1.MongoUpstreamSink; } });
+Object.defineProperty(exports, "VERSION_FIELD", { enumerable: true, get: function () { return mongoSink_js_1.VERSION_FIELD; } });
+Object.defineProperty(exports, "UPDATED_AT_FIELD", { enumerable: true, get: function () { return mongoSink_js_1.UPDATED_AT_FIELD; } });
+var httpSink_js_1 = require("./httpSink.js");
+Object.defineProperty(exports, "HttpUpstreamSink", { enumerable: true, get: function () { return httpSink_js_1.HttpUpstreamSink; } });
+Object.defineProperty(exports, "SyncRequestRejected", { enumerable: true, get: function () { return httpSink_js_1.SyncRequestRejected; } });
+var commands_js_1 = require("./commands.js");
+Object.defineProperty(exports, "buildWriteCommand", { enumerable: true, get: function () { return commands_js_1.buildWriteCommand; } });
+Object.defineProperty(exports, "toUpstreamId", { enumerable: true, get: function () { return commands_js_1.toUpstreamId; } });
+var mongoExecutor_js_1 = require("./mongoExecutor.js");
+Object.defineProperty(exports, "executeWrites", { enumerable: true, get: function () { return mongoExecutor_js_1.executeWrites; } });
+Object.defineProperty(exports, "fetchDocuments", { enumerable: true, get: function () { return mongoExecutor_js_1.fetchDocuments; } });
+var protocol_js_1 = require("./protocol.js");
+Object.defineProperty(exports, "SYNC_PROTOCOL_VERSION", { enumerable: true, get: function () { return protocol_js_1.SYNC_PROTOCOL_VERSION; } });
+Object.defineProperty(exports, "SyncProtocolError", { enumerable: true, get: function () { return protocol_js_1.SyncProtocolError; } });
+Object.defineProperty(exports, "encodeBody", { enumerable: true, get: function () { return protocol_js_1.encodeBody; } });
+Object.defineProperty(exports, "decodeBody", { enumerable: true, get: function () { return protocol_js_1.decodeBody; } });
+Object.defineProperty(exports, "toWireOperation", { enumerable: true, get: function () { return protocol_js_1.toWireOperation; } });
+Object.defineProperty(exports, "fromWireOperation", { enumerable: true, get: function () { return protocol_js_1.fromWireOperation; } });
+var shadow_js_1 = require("./shadow.js");
+Object.defineProperty(exports, "SyncShadow", { enumerable: true, get: function () { return shadow_js_1.SyncShadow; } });
+Object.defineProperty(exports, "SHADOW_TABLE", { enumerable: true, get: function () { return shadow_js_1.SHADOW_TABLE; } });
+Object.defineProperty(exports, "projectToLocalShape", { enumerable: true, get: function () { return shadow_js_1.projectToLocalShape; } });
+var diff_js_1 = require("./diff.js");
+Object.defineProperty(exports, "computeDiff", { enumerable: true, get: function () { return diff_js_1.computeDiff; } });
+Object.defineProperty(exports, "applyDiff", { enumerable: true, get: function () { return diff_js_1.applyDiff; } });
+Object.defineProperty(exports, "isEmptyDiff", { enumerable: true, get: function () { return diff_js_1.isEmptyDiff; } });
+Object.defineProperty(exports, "deepEqual", { enumerable: true, get: function () { return diff_js_1.deepEqual; } });