@semics-tech/mongolite 1.3.0 → 1.4.0

package/dist/sync/outbox.d.ts

@@ -0,0 +1,120 @@
+/**
+ * The durable change log ("outbox") that backs MongoDB replication.
+ *
+ * SQLite triggers append a row here inside the very same transaction as the
+ * write that caused it, so a change is either committed locally *and* queued for
+ * replication, or neither. Replicators then drain the log at their own pace and
+ * record a checkpoint; nothing is dropped because the process crashed or the
+ * upstream was unreachable.
+ */
+import type { IDatabaseAdapter } from '../db.js';
+import type { SyncDeadLetter, SyncOutboxRecord } from './types.js';
+export declare const OUTBOX_TABLE = "__mongolite_sync_outbox__";
+export declare const STATE_TABLE = "__mongolite_sync_state__";
+export declare const DEAD_LETTER_TABLE = "__mongolite_sync_deadletter__";
+/** Prefix shared by every table and trigger this module creates. */
+export declare const SYNC_OBJECT_PREFIX = "__mongolite_sync";
+/**
+ * Owns the outbox tables, the capture triggers, and every replicator's
+ * checkpoint. A single outbox serves any number of replicators: each keeps its
+ * own checkpoint row, and rows are pruned only once *every* replicator has
+ * passed them.
+ */
+export declare class SyncOutbox {
+    private readonly db;
+    private schemaReady;
+    private readonly installedTriggers;
+    constructor(db: IDatabaseAdapter);
+    /** Creates the outbox, checkpoint and dead-letter tables. Idempotent. */
+    ensureSchema(): Promise<void>;
+    private createSchema;
+    /**
+     * Installs the insert/update/delete capture triggers for a collection.
+     *
+     * Triggers deliberately outlive the replicator that created them: changes made
+     * while replication is stopped still need to be captured, or restarting would
+     * silently skip them. Use {@link SyncOutbox.removeTriggers} to opt out.
+     */
+    ensureTriggers(collection: string): Promise<void>;
+    /**
+     * Removes the capture triggers for a collection. Changes to it stop being
+     * recorded — existing queued rows are untouched.
+     */
+    removeTriggers(collection: string): Promise<void>;
+    /** Lists user collections, excluding MongoLite's own bookkeeping tables. */
+    listCollections(): Promise<string[]>;
+    /**
+     * Reconciles the in-memory "already installed" cache with what is actually in
+     * the schema.
+     *
+     * Dropping a table drops its triggers with it, so a collection that was
+     * dropped and recreated would otherwise be silently uncaptured — the cache
+     * would insist its triggers were still there.
+     */
+    refreshTriggerCache(): Promise<void>;
+    /** The newest outbox id, or 0 when the log is empty. */
+    currentSequence(): Promise<number>;
+    /** Reads the persisted checkpoint for a replicator, creating its state row if absent. */
+    loadState(name: string): Promise<{
+        checkpoint: number;
+        backfilled: string[];
+    }>;
+    /**
+     * Advances a replicator's checkpoint.
+     *
+     * This is the acknowledgement, and it is a single atomic statement: a crash
+     * either leaves the old checkpoint (the batch is replayed, which is safe
+     * because upstream writes are idempotent) or the new one.
+     */
+    saveCheckpoint(name: string, checkpoint: number): Promise<void>;
+    /** Records that a collection's existing contents have been backfilled. */
+    markBackfilled(name: string, collections: string[]): Promise<void>;
+    /** Forgets a replicator, releasing the outbox rows its checkpoint was pinning. */
+    unregister(name: string): Promise<void>;
+    /** Reads the next batch of changes after `checkpoint`, oldest first. */
+    readBatch(checkpoint: number, limit: number, collections: string[] | null): Promise<SyncOutboxRecord[]>;
+    /** Count of rows a replicator still has to apply. */
+    pendingCount(checkpoint: number, collections: string[] | null): Promise<number>;
+    /**
+     * Deletes rows every registered replicator has already applied.
+     * @returns Number of rows removed.
+     */
+    prune(): Promise<number>;
+    /**
+     * Drops superseded revisions, keeping only the newest row per document.
+     *
+     * Safe because replication carries whole documents rather than deltas: the
+     * newest row alone reproduces the same upstream state. Rows at or below the
+     * slowest replicator's checkpoint are left to {@link SyncOutbox.prune}.
+     *
+     * @returns Number of rows removed.
+     */
+    compact(): Promise<number>;
+    /**
+     * Appends a change back onto the log so it is retried on a later drain.
+     *
+     * Used when a conflict is resolved in favour of the local version: the shadow has
+     * since been refreshed, so the replayed push diffs against current upstream state and
+     * carries the version it actually lost to.
+     */
+    requeue(collection: string, documentId: string, document: Record<string, unknown> | null): Promise<void>;
+    /** Moves a permanently-rejected change out of the stream so it cannot stall replication. */
+    deadLetter(replicator: string, record: {
+        collection: string;
+        documentId: string;
+        operation: string;
+        document: unknown;
+    }, error: string): Promise<void>;
+    /** Reads dead-lettered changes, newest first. */
+    listDeadLetters(replicator?: string, limit?: number): Promise<SyncDeadLetter[]>;
+    /** Removes dead-lettered rows, e.g. after replaying them by hand. */
+    clearDeadLetters(replicator?: string): Promise<number>;
+    /**
+     * Streams a collection's current contents in `_id` order, for the initial
+     * backfill. Keyset pagination keeps memory flat on large collections.
+     */
+    scanCollection(collection: string, chunkSize: number): AsyncGenerator<Array<{
+        documentId: string;
+        document: Record<string, unknown> | null;
+    }>>;
+}

package/dist/sync/outbox.js

@@ -0,0 +1,355 @@
+export const OUTBOX_TABLE = '__mongolite_sync_outbox__';
+export const STATE_TABLE = '__mongolite_sync_state__';
+export const DEAD_LETTER_TABLE = '__mongolite_sync_deadletter__';
+/** Prefix shared by every table and trigger this module creates. */
+export const SYNC_OBJECT_PREFIX = '__mongolite_sync';
+/** Quotes a SQL identifier, escaping any embedded double quotes. */
+function quoteIdent(name) {
+    return `"${name.replace(/"/g, '""')}"`;
+}
+/** Quotes a SQL string literal, escaping any embedded single quotes. */
+function quoteLiteral(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+/** Millisecond epoch as a SQL expression — portable across SQLite builds. */
+const NOW_MS_SQL = `CAST((julianday('now') - 2440587.5) * 86400000.0 AS INTEGER)`;
+function triggerName(collection, operation) {
+    return `${SYNC_OBJECT_PREFIX}_${operation}__${collection}`;
+}
+/**
+ * Owns the outbox tables, the capture triggers, and every replicator's
+ * checkpoint. A single outbox serves any number of replicators: each keeps its
+ * own checkpoint row, and rows are pruned only once *every* replicator has
+ * passed them.
+ */
+export class SyncOutbox {
+    constructor(db) {
+        this.db = db;
+        this.schemaReady = null;
+        this.installedTriggers = new Set();
+    }
+    /** Creates the outbox, checkpoint and dead-letter tables. Idempotent. */
+    async ensureSchema() {
+        if (!this.schemaReady) {
+            this.schemaReady = this.createSchema().catch((err) => {
+                // Let a later call retry rather than caching the failure forever.
+                this.schemaReady = null;
+                throw err;
+            });
+        }
+        return this.schemaReady;
+    }
+    async createSchema() {
+        await this.db.exec(`
+      CREATE TABLE IF NOT EXISTS ${OUTBOX_TABLE} (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        collection_name TEXT NOT NULL,
+        document_id TEXT NOT NULL,
+        operation TEXT NOT NULL,
+        full_document TEXT,
+        captured_at INTEGER NOT NULL
+      );
+    `);
+        await this.db.exec(`
+      CREATE INDEX IF NOT EXISTS ${SYNC_OBJECT_PREFIX}_outbox_key
+      ON ${OUTBOX_TABLE} (collection_name, document_id, id);
+    `);
+        await this.db.exec(`
+      CREATE TABLE IF NOT EXISTS ${STATE_TABLE} (
+        name TEXT PRIMARY KEY,
+        checkpoint INTEGER NOT NULL DEFAULT 0,
+        backfilled TEXT NOT NULL DEFAULT '[]',
+        updated_at INTEGER NOT NULL DEFAULT 0
+      );
+    `);
+        await this.db.exec(`
+      CREATE TABLE IF NOT EXISTS ${DEAD_LETTER_TABLE} (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        replicator TEXT NOT NULL,
+        collection_name TEXT NOT NULL,
+        document_id TEXT NOT NULL,
+        operation TEXT NOT NULL,
+        full_document TEXT,
+        error TEXT NOT NULL,
+        failed_at INTEGER NOT NULL
+      );
+    `);
+    }
+    /**
+     * Installs the insert/update/delete capture triggers for a collection.
+     *
+     * Triggers deliberately outlive the replicator that created them: changes made
+     * while replication is stopped still need to be captured, or restarting would
+     * silently skip them. Use {@link SyncOutbox.removeTriggers} to opt out.
+     */
+    async ensureTriggers(collection) {
+        if (this.installedTriggers.has(collection))
+            return;
+        await this.ensureSchema();
+        const table = quoteIdent(collection);
+        const literal = quoteLiteral(collection);
+        const insert = (op, row, doc) => `
+      CREATE TRIGGER IF NOT EXISTS ${quoteIdent(triggerName(collection, op))}
+      AFTER ${op === 'insert' ? 'INSERT' : op === 'update' ? 'UPDATE' : 'DELETE'} ON ${table}
+      FOR EACH ROW
+      BEGIN
+        INSERT INTO ${OUTBOX_TABLE}
+          (collection_name, document_id, operation, full_document, captured_at)
+        VALUES
+          (${literal}, ${row}._id, ${quoteLiteral(op)}, ${doc}, ${NOW_MS_SQL});
+      END;
+    `;
+        await this.db.exec(insert('insert', 'NEW', 'NEW.data'));
+        await this.db.exec(insert('update', 'NEW', 'NEW.data'));
+        await this.db.exec(insert('delete', 'OLD', 'NULL'));
+        this.installedTriggers.add(collection);
+    }
+    /**
+     * Removes the capture triggers for a collection. Changes to it stop being
+     * recorded — existing queued rows are untouched.
+     */
+    async removeTriggers(collection) {
+        for (const op of ['insert', 'update', 'delete']) {
+            await this.db.exec(`DROP TRIGGER IF EXISTS ${quoteIdent(triggerName(collection, op))}`);
+        }
+        this.installedTriggers.delete(collection);
+    }
+    /** Lists user collections, excluding MongoLite's own bookkeeping tables. */
+    async listCollections() {
+        const rows = await this.db.all(`SELECT name FROM sqlite_master
+       WHERE type = 'table' AND name NOT LIKE 'sqlite_%' AND name NOT LIKE '__mongolite%'
+       ORDER BY name`);
+        return rows.map((row) => row.name);
+    }
+    /**
+     * Reconciles the in-memory "already installed" cache with what is actually in
+     * the schema.
+     *
+     * Dropping a table drops its triggers with it, so a collection that was
+     * dropped and recreated would otherwise be silently uncaptured — the cache
+     * would insist its triggers were still there.
+     */
+    async refreshTriggerCache() {
+        const rows = await this.db.all(`SELECT name FROM sqlite_master WHERE type = 'trigger' AND name LIKE '${SYNC_OBJECT_PREFIX}\\_%' ESCAPE '\\'`);
+        const present = new Set(rows.map((row) => row.name));
+        for (const collection of [...this.installedTriggers]) {
+            const complete = ['insert', 'update', 'delete'].every((op) => present.has(triggerName(collection, op)));
+            if (!complete)
+                this.installedTriggers.delete(collection);
+        }
+    }
+    /** The newest outbox id, or 0 when the log is empty. */
+    async currentSequence() {
+        const row = await this.db.get(`SELECT MAX(id) AS seq FROM ${OUTBOX_TABLE}`);
+        return row?.seq ?? 0;
+    }
+    /** Reads the persisted checkpoint for a replicator, creating its state row if absent. */
+    async loadState(name) {
+        await this.ensureSchema();
+        const row = await this.db.get(`SELECT checkpoint, backfilled FROM ${STATE_TABLE} WHERE name = ?`, [name]);
+        if (row) {
+            let backfilled = [];
+            try {
+                const parsed = JSON.parse(row.backfilled);
+                if (Array.isArray(parsed))
+                    backfilled = parsed.filter((v) => typeof v === 'string');
+            }
+            catch {
+                // Corrupt bookkeeping should not wedge replication; treat as "nothing backfilled".
+            }
+            return { checkpoint: Number(row.checkpoint) || 0, backfilled };
+        }
+        // A brand new replicator starts from the current tail. Anything already in
+        // the collections is handled by the backfill, not by replaying the log.
+        const checkpoint = await this.currentSequence();
+        await this.db.run(`INSERT INTO ${STATE_TABLE} (name, checkpoint, backfilled, updated_at)
+       VALUES (?, ?, '[]', ${NOW_MS_SQL})`, [name, checkpoint]);
+        return { checkpoint, backfilled: [] };
+    }
+    /**
+     * Advances a replicator's checkpoint.
+     *
+     * This is the acknowledgement, and it is a single atomic statement: a crash
+     * either leaves the old checkpoint (the batch is replayed, which is safe
+     * because upstream writes are idempotent) or the new one.
+     */
+    async saveCheckpoint(name, checkpoint) {
+        await this.db.run(`UPDATE ${STATE_TABLE} SET checkpoint = ?, updated_at = ${NOW_MS_SQL} WHERE name = ?`, [checkpoint, name]);
+    }
+    /** Records that a collection's existing contents have been backfilled. */
+    async markBackfilled(name, collections) {
+        await this.db.run(`UPDATE ${STATE_TABLE} SET backfilled = ?, updated_at = ${NOW_MS_SQL} WHERE name = ?`, [JSON.stringify(collections), name]);
+    }
+    /** Forgets a replicator, releasing the outbox rows its checkpoint was pinning. */
+    async unregister(name) {
+        await this.ensureSchema();
+        await this.db.run(`DELETE FROM ${STATE_TABLE} WHERE name = ?`, [name]);
+    }
+    /** Reads the next batch of changes after `checkpoint`, oldest first. */
+    async readBatch(checkpoint, limit, collections) {
+        const params = [checkpoint];
+        let filter = '';
+        if (collections) {
+            if (collections.length === 0)
+                return [];
+            filter = ` AND collection_name IN (${collections.map(() => '?').join(', ')})`;
+            params.push(...collections);
+        }
+        params.push(limit);
+        const rows = await this.db.all(`SELECT id, collection_name, document_id, operation, full_document, captured_at
+       FROM ${OUTBOX_TABLE}
+       WHERE id > ?${filter}
+       ORDER BY id ASC
+       LIMIT ?`, params);
+        return rows.map((row) => ({
+            id: Number(row.id),
+            collection: row.collection_name,
+            documentId: row.document_id,
+            operation: row.operation,
+            document: parseDocument(row.full_document, row.document_id),
+            capturedAt: Number(row.captured_at),
+        }));
+    }
+    /** Count of rows a replicator still has to apply. */
+    async pendingCount(checkpoint, collections) {
+        const params = [checkpoint];
+        let filter = '';
+        if (collections) {
+            if (collections.length === 0)
+                return 0;
+            filter = ` AND collection_name IN (${collections.map(() => '?').join(', ')})`;
+            params.push(...collections);
+        }
+        const row = await this.db.get(`SELECT COUNT(*) AS total FROM ${OUTBOX_TABLE} WHERE id > ?${filter}`, params);
+        return Number(row?.total ?? 0);
+    }
+    /**
+     * Deletes rows every registered replicator has already applied.
+     * @returns Number of rows removed.
+     */
+    async prune() {
+        const row = await this.db.get(`SELECT MIN(checkpoint) AS floor FROM ${STATE_TABLE}`);
+        const floor = row?.floor;
+        if (floor === null || floor === undefined)
+            return 0;
+        const result = await this.db.run(`DELETE FROM ${OUTBOX_TABLE} WHERE id <= ?`, [floor]);
+        return result.changes;
+    }
+    /**
+     * Drops superseded revisions, keeping only the newest row per document.
+     *
+     * Safe because replication carries whole documents rather than deltas: the
+     * newest row alone reproduces the same upstream state. Rows at or below the
+     * slowest replicator's checkpoint are left to {@link SyncOutbox.prune}.
+     *
+     * @returns Number of rows removed.
+     */
+    async compact() {
+        const result = await this.db.run(`DELETE FROM ${OUTBOX_TABLE}
+       WHERE id NOT IN (
+         SELECT MAX(id) FROM ${OUTBOX_TABLE} GROUP BY collection_name, document_id
+       )
+       AND id > COALESCE((SELECT MIN(checkpoint) FROM ${STATE_TABLE}), 0)`);
+        return result.changes;
+    }
+    /**
+     * Appends a change back onto the log so it is retried on a later drain.
+     *
+     * Used when a conflict is resolved in favour of the local version: the shadow has
+     * since been refreshed, so the replayed push diffs against current upstream state and
+     * carries the version it actually lost to.
+     */
+    async requeue(collection, documentId, document) {
+        await this.ensureSchema();
+        // `_id` lives in its own column locally and is re-attached on read, so it is
+        // stripped here to match what the capture triggers store.
+        let payload = null;
+        if (document) {
+            const rest = { ...document };
+            delete rest._id;
+            payload = JSON.stringify(rest);
+        }
+        await this.db.run(`INSERT INTO ${OUTBOX_TABLE}
+         (collection_name, document_id, operation, full_document, captured_at)
+       VALUES (?, ?, ?, ?, ${NOW_MS_SQL})`, [collection, documentId, document ? 'update' : 'delete', payload]);
+    }
+    /** Moves a permanently-rejected change out of the stream so it cannot stall replication. */
+    async deadLetter(replicator, record, error) {
+        await this.db.run(`INSERT INTO ${DEAD_LETTER_TABLE}
+         (replicator, collection_name, document_id, operation, full_document, error, failed_at)
+       VALUES (?, ?, ?, ?, ?, ?, ${NOW_MS_SQL})`, [
+            replicator,
+            record.collection,
+            record.documentId,
+            record.operation,
+            record.document === null || record.document === undefined
+                ? null
+                : JSON.stringify(record.document),
+            error,
+        ]);
+    }
+    /** Reads dead-lettered changes, newest first. */
+    async listDeadLetters(replicator, limit = 100) {
+        await this.ensureSchema();
+        const where = replicator ? 'WHERE replicator = ?' : '';
+        const params = replicator ? [replicator, limit] : [limit];
+        const rows = await this.db.all(`SELECT id, collection_name, document_id, operation, full_document, error, failed_at
+       FROM ${DEAD_LETTER_TABLE} ${where} ORDER BY id DESC LIMIT ?`, params);
+        return rows.map((row) => ({
+            id: Number(row.id),
+            collection: row.collection_name,
+            documentId: row.document_id,
+            operation: row.operation,
+            document: parseDocument(row.full_document, row.document_id),
+            error: row.error,
+            failedAt: Number(row.failed_at),
+        }));
+    }
+    /** Removes dead-lettered rows, e.g. after replaying them by hand. */
+    async clearDeadLetters(replicator) {
+        await this.ensureSchema();
+        const result = replicator
+            ? await this.db.run(`DELETE FROM ${DEAD_LETTER_TABLE} WHERE replicator = ?`, [replicator])
+            : await this.db.run(`DELETE FROM ${DEAD_LETTER_TABLE}`);
+        return result.changes;
+    }
+    /**
+     * Streams a collection's current contents in `_id` order, for the initial
+     * backfill. Keyset pagination keeps memory flat on large collections.
+     */
+    async *scanCollection(collection, chunkSize) {
+        // `null` on the first pass so an empty-string `_id` is not skipped.
+        let after = null;
+        for (;;) {
+            const rows = await this.db.all(`SELECT _id, data FROM ${quoteIdent(collection)}
+         ${after === null ? '' : 'WHERE _id > ?'}
+         ORDER BY _id ASC LIMIT ?`, after === null ? [chunkSize] : [after, chunkSize]);
+            if (rows.length === 0)
+                return;
+            yield rows.map((row) => ({
+                documentId: row._id,
+                document: parseDocument(row.data, row._id),
+            }));
+            after = rows[rows.length - 1]._id;
+        }
+    }
+}
+/**
+ * Parses a stored document, re-attaching the `_id` that lives in its own column.
+ * Returns `null` for deletes and for rows whose JSON is unreadable — the caller
+ * dead-letters the latter rather than crashing the replicator.
+ */
+function parseDocument(json, documentId) {
+    if (json === null || json === undefined)
+        return null;
+    try {
+        const parsed = JSON.parse(json);
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+            return null;
+        return { _id: documentId, ...parsed };
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=outbox.js.map

package/dist/sync/outbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox.js","sourceRoot":"","sources":["../../src/sync/outbox.ts"],"names":[],"mappings":"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"}

package/dist/sync/protocol.d.ts

@@ -0,0 +1,93 @@
+import type { MongoWriteCommand } from './commands.js';
+import type { SyncApplyConflict, SyncApplyFailure, SyncOperation } from './types.js';
+/**
+ * Protocol version, sent with every request.
+ *
+ * A receiver rejects a version it does not understand rather than guessing, so an
+ * upgraded client talking to an old server fails loudly instead of silently writing
+ * something unintended.
+ */
+export declare const SYNC_PROTOCOL_VERSION = 1;
+/** Content type used for request and response bodies. */
+export declare const SYNC_CONTENT_TYPE = "application/json";
+/** One operation as it crosses the wire. */
+export interface WireOperation {
+    /** Upstream collection name, after any renaming. */
+    collection: string;
+    documentId: string;
+    type: 'upsert' | 'delete';
+    /** Upstream `_v` this operation asserts against; `null` when the document is new. */
+    baseVersion?: number | null;
+    /** Field-level change, when a shadow existed to diff against. */
+    diff?: {
+        set: Record<string, unknown>;
+        unset: string[];
+    };
+    /** Full document, for creates and for the unversioned mode. */
+    document?: Record<string, unknown>;
+    /**
+     * The MongoDB command this operation resolves to.
+     *
+     * Sent so a forwarding API can inspect or pass it straight through. The receiver
+     * **rebuilds it** from the fields above rather than executing it, unless explicitly
+     * configured to trust the client — see `createSyncReceiver`.
+     */
+    command?: MongoWriteCommand;
+}
+/** Body of a write request. */
+export interface SyncApplyRequest {
+    protocol: number;
+    /** Replicator name, for server-side logging and rate limiting. */
+    replicator?: string;
+    operations: WireOperation[];
+}
+/** Body of a write response — mirrors `SyncApplyResult`. */
+export interface SyncApplyResponse {
+    protocol: number;
+    applied: number;
+    failures?: SyncApplyFailure[];
+    conflicts?: SyncApplyConflict[];
+}
+/** Body of a read-back request, used to refresh a shadow after a conflict. */
+export interface SyncFetchRequest {
+    protocol: number;
+    collection: string;
+    documentIds: string[];
+}
+/** Body of a read-back response. */
+export interface SyncFetchResponse {
+    protocol: number;
+    documents: Record<string, unknown>[];
+}
+/** Raised when a payload is malformed or speaks a version we do not implement. */
+export declare class SyncProtocolError extends Error {
+    /** Suggested HTTP status for a receiver to return. */
+    readonly status: number;
+    constructor(message: string, 
+    /** Suggested HTTP status for a receiver to return. */
+    status?: number);
+}
+/** Serialises a body to relaxed Extended JSON. */
+export declare function encodeBody(value: unknown): string;
+/** Parses a relaxed Extended JSON body back into BSON-typed values. */
+export declare function decodeBody<T>(raw: string | Record<string, unknown>): T;
+/** Converts an internal operation into its wire form. */
+export declare function toWireOperation(op: SyncOperation, command?: MongoWriteCommand): WireOperation;
+/**
+ * Validates a wire operation and converts it back into an internal one.
+ *
+ * Everything reaching a receiver is untrusted input, so this checks shape rather than
+ * assuming it. `index` and `sourceCollection` are reconstructed locally — a client does
+ * not get to choose them.
+ */
+export declare function fromWireOperation(value: unknown, index: number): SyncOperation;
+/** Validates the envelope of an apply request and returns its operations. */
+export declare function parseApplyRequest(body: unknown): {
+    replicator: string;
+    operations: SyncOperation[];
+};
+/** Validates the envelope of a fetch request. */
+export declare function parseFetchRequest(body: unknown): {
+    collection: string;
+    documentIds: string[];
+};