@semics-tech/mongolite 1.3.0 → 1.4.0

package/dist/sync/diff.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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.
+ */
+/** A minimal update expressed as dotted-path assignments and removals. */
+export interface DocumentDiff {
+    /** Dotted path → new value. */
+    set: Record<string, unknown>;
+    /** Dotted paths to remove. */
+    unset: string[];
+}
+/**
+ * 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.
+ */
+export declare function deepEqual(a: unknown, b: unknown): boolean;
+/**
+ * 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.
+ */
+export declare function computeDiff(base: Record<string, unknown> | null, local: Record<string, unknown>): DocumentDiff;
+/** True when the diff would change nothing upstream. */
+export declare function isEmptyDiff(diff: DocumentDiff): boolean;
+/**
+ * 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.
+ */
+export declare function applyDiff(document: Record<string, unknown>, diff: DocumentDiff): Record<string, unknown>;

package/dist/sync/diff.js

@@ -0,0 +1,169 @@
+/**
+ * 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.
+ */
+/**
+ * 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.
+ */
+export 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.
+ */
+export 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. */
+export 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.
+ */
+export 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);
+}
+//# sourceMappingURL=diff.js.map

package/dist/sync/diff.js.map

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

package/dist/sync/httpSink.d.ts

@@ -0,0 +1,93 @@
+import type { SyncApplyResult, SyncIdMapping, SyncOperation, SyncSink } from './types.js';
+/** The subset of the global `fetch` signature this sink relies on. */
+export type FetchLike = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+    text(): Promise<string>;
+}>;
+export interface HttpSinkOptions {
+    /** Base URL of the remote API, e.g. `https://api.example.com`. */
+    baseUrl: string;
+    /** Target database name, included in the request path. */
+    database: string;
+    /** Path segment before the database. Defaults to `'sync'`. */
+    pathPrefix?: string;
+    /**
+     * Headers to attach to every request, resolved per request so short-lived tokens can
+     * be refreshed. Anything static belongs in {@link HttpSinkOptions.headers}.
+     *
+     * @example
+     * ```ts
+     * getAuthHeaders: async () => ({ Authorization: `Bearer ${await getAccessToken()}` })
+     * ```
+     */
+    getAuthHeaders?: () => Promise<Record<string, string>> | Record<string, string>;
+    /** Static headers sent with every request. */
+    headers?: Record<string, string>;
+    /**
+     * Capture and replay `set-cookie`, for APIs that use a session cookie for affinity
+     * after the first authenticated request. Defaults to `true`.
+     */
+    cookies?: boolean;
+    /**
+     * `fetch` implementation. Defaults to the global one (Node 18+).
+     *
+     * Supply your own to get interceptors, connection pooling or proxy support — for
+     * example `ofetch`. Note that retries are handled by the replicator, so a fetch layer
+     * configured to retry will compound with that rather than replace it.
+     */
+    fetch?: FetchLike;
+    /** Per-request timeout in ms. Defaults to `30_000`. */
+    timeoutMs?: number;
+    /** See {@link SyncIdMapping}. Defaults to `'auto'`. */
+    idMapping?: SyncIdMapping;
+    /** Conditional writes against `_v`. Defaults to `true`. */
+    versioning?: boolean;
+    /**
+     * Include the built MongoDB command alongside each operation. Defaults to `true`,
+     * so a forwarding API can pass it straight through. Turn it off to halve payload
+     * size when the receiver rebuilds commands anyway (which it does by default).
+     */
+    includeCommands?: boolean;
+    /** Replicator name, sent for server-side logging. */
+    replicator?: string;
+}
+export declare class HttpUpstreamSink implements SyncSink {
+    private readonly options;
+    readonly name = "http";
+    private readonly fetchImpl;
+    private readonly idMapping;
+    private readonly versioning;
+    private cookie;
+    constructor(options: HttpSinkOptions);
+    apply(operations: SyncOperation[]): Promise<SyncApplyResult>;
+    fetch(collection: string, documentIds: string[]): Promise<Record<string, unknown>[]>;
+    private endpoint;
+    private requestHeaders;
+    /**
+     * 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.
+     */
+    private send;
+}
+/**
+ * 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.
+ */
+export declare class SyncRequestRejected extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}

package/dist/sync/httpSink.js

@@ -0,0 +1,155 @@
+/**
+ * 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.
+ */
+import { buildWriteCommand } from './commands.js';
+import { SYNC_PROTOCOL_VERSION, SYNC_CONTENT_TYPE, decodeBody, encodeBody, toWireOperation, } from './protocol.js';
+export 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: SYNC_PROTOCOL_VERSION,
+            replicator: this.options.replicator,
+            operations: operations.map((op) => toWireOperation(op, includeCommands
+                ? 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: 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': SYNC_CONTENT_TYPE,
+            accept: 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: 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 decodeBody(text);
+    }
+}
+/**
+ * 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.
+ */
+export class SyncRequestRejected extends Error {
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = 'SyncRequestRejected';
+    }
+}
+//# sourceMappingURL=httpSink.js.map

package/dist/sync/httpSink.js.map

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

package/dist/sync/index.d.ts

@@ -0,0 +1,17 @@
+export { SyncReplicator } from './replicator.js';
+export { SyncOutbox, OUTBOX_TABLE, STATE_TABLE, DEAD_LETTER_TABLE, SYNC_OBJECT_PREFIX, } from './outbox.js';
+export { MongoUpstreamSink, VERSION_FIELD, UPDATED_AT_FIELD } from './mongoSink.js';
+export type { MongoSinkOptions, MongoUpstreamAuth } from './mongoSink.js';
+export { HttpUpstreamSink, SyncRequestRejected } from './httpSink.js';
+export type { HttpSinkOptions, FetchLike } from './httpSink.js';
+export { buildWriteCommand, toUpstreamId } from './commands.js';
+export type { MongoWriteCommand, BuildCommandOptions, ObjectIdFactory } from './commands.js';
+export { executeWrites, fetchDocuments } from './mongoExecutor.js';
+export type { PreparedWrite, ExecuteOptions } from './mongoExecutor.js';
+export { SYNC_PROTOCOL_VERSION, SyncProtocolError, encodeBody, decodeBody, toWireOperation, fromWireOperation, } from './protocol.js';
+export type { SyncApplyRequest, SyncApplyResponse, SyncFetchRequest, SyncFetchResponse, WireOperation, } from './protocol.js';
+export { SyncShadow, SHADOW_TABLE, projectToLocalShape } from './shadow.js';
+export type { ShadowEntry } from './shadow.js';
+export { computeDiff, applyDiff, isEmptyDiff, deepEqual } from './diff.js';
+export type { DocumentDiff } from './diff.js';
+export type { MongoBulkWriteResultLike, SyncApplyConflict, SyncApplyFailure, SyncApplyResult, SyncConflictContext, SyncConflictReason, SyncConflictResolution, SyncCollectionOptions, SyncDeadLetter, SyncEvents, SyncIdMapping, SyncInitialMode, SyncOperation, SyncOperationType, SyncOptions, SyncOutboxRecord, SyncOverflowStrategy, SyncSink, SyncStatus, } from './types.js';

package/dist/sync/index.js

@@ -0,0 +1,10 @@
+export { SyncReplicator } from './replicator.js';
+export { SyncOutbox, OUTBOX_TABLE, STATE_TABLE, DEAD_LETTER_TABLE, SYNC_OBJECT_PREFIX, } from './outbox.js';
+export { MongoUpstreamSink, VERSION_FIELD, UPDATED_AT_FIELD } from './mongoSink.js';
+export { HttpUpstreamSink, SyncRequestRejected } from './httpSink.js';
+export { buildWriteCommand, toUpstreamId } from './commands.js';
+export { executeWrites, fetchDocuments } from './mongoExecutor.js';
+export { SYNC_PROTOCOL_VERSION, SyncProtocolError, encodeBody, decodeBody, toWireOperation, fromWireOperation, } from './protocol.js';
+export { SyncShadow, SHADOW_TABLE, projectToLocalShape } from './shadow.js';
+export { computeDiff, applyDiff, isEmptyDiff, deepEqual } from './diff.js';
+//# sourceMappingURL=index.js.map

package/dist/sync/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sync/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EACL,UAAU,EACV,YAAY,EACZ,WAAW,EACX,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEpF,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEtE,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAEhE,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEnE,OAAO,EACL,qBAAqB,EACrB,iBAAiB,EACjB,UAAU,EACV,UAAU,EACV,eAAe,EACf,iBAAiB,GAClB,MAAM,eAAe,CAAC;AAQvB,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAE5E,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC"}

package/dist/sync/mongoExecutor.d.ts

@@ -0,0 +1,37 @@
+import type { MongoWriteCommand, ObjectIdFactory } from './commands.js';
+import type { MongoDbLike, SyncApplyResult, SyncIdMapping, SyncOperation } from './types.js';
+/** One operation paired with the command that realises it. */
+export interface PreparedWrite {
+    /** Index into the caller's original operations array, echoed back in results. */
+    index: number;
+    op: SyncOperation;
+    command: MongoWriteCommand;
+}
+export interface ExecuteOptions {
+    writeConcern?: Record<string, unknown>;
+    versioning?: boolean;
+    idMapping?: SyncIdMapping;
+    ObjectId?: ObjectIdFactory;
+}
+/**
+ * Runs prepared writes against a database, one `bulkWrite` per collection.
+ *
+ * Throws on transient failure (network, election, timeout) so the caller retries the
+ * whole batch without checkpointing. Returns per-operation failures and conflicts for
+ * everything it could classify.
+ */
+export declare function executeWrites(db: MongoDbLike, writes: PreparedWrite[], options?: ExecuteOptions): Promise<SyncApplyResult>;
+/**
+ * Splits a driver error into per-operation permanent failures.
+ *
+ * @returns The failures to dead-letter, or `null` when the error is transient and the
+ * whole batch should be retried.
+ */
+export declare function classifyBulkError(err: unknown, operationCount: number): Array<{
+    index: number;
+    message: string;
+    code?: number | string;
+    keyPattern?: Record<string, unknown>;
+}> | null;
+/** Reads documents back by `_id`, for refreshing a shadow after a conflict. */
+export declare function fetchDocuments(db: MongoDbLike, collection: string, documentIds: string[], idMapping?: SyncIdMapping, ObjectId?: ObjectIdFactory): Promise<Record<string, unknown>[]>;