@semics-tech/mongolite 1.3.0 → 1.4.1

package/dist/sync/replicator.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Drains the {@link SyncOutbox} into an upstream {@link SyncSink}.
+ *
+ * ## Delivery guarantees
+ *
+ * Delivery is **at-least-once**, and every operation the replicator emits is
+ * idempotent (`replaceOne` with `upsert`, or `deleteOne` by `_id`). Replaying a
+ * batch therefore converges on the same upstream state, which is what makes it
+ * safe to acknowledge *after* the upstream write rather than before: a crash in
+ * the window between the two costs a duplicate write, never a lost one.
+ *
+ * ## Ordering
+ *
+ * Changes are read in outbox order and coalesced per document, so the newest
+ * revision wins. Within a batch, operations touch distinct documents and are
+ * applied unordered for throughput; across batches, order is preserved.
+ */
+import { EventEmitter } from 'events';
+import type { IDatabaseAdapter } from '../db.js';
+import { SyncOutbox } from './outbox.js';
+import { SyncShadow } from './shadow.js';
+import type { SyncDeadLetter, SyncOptions, SyncSink, SyncStatus } from './types.js';
+export declare class SyncReplicator extends EventEmitter {
+    private readonly db;
+    private readonly sink;
+    private readonly outbox;
+    private readonly shadow;
+    private readonly opts;
+    private running;
+    private connected;
+    private loop;
+    private checkpoint;
+    private backfilled;
+    private watched;
+    private lastCollectionScan;
+    private appliedCount;
+    private retryCount;
+    private deadLetterCount;
+    private conflictCount;
+    private lastError;
+    /** Resolves the current sleep early when a local write arrives or `stop()` is called. */
+    private wake;
+    constructor(db: IDatabaseAdapter, sink: SyncSink, options?: SyncOptions);
+    /** The outbox backing this replicator — for dead-letter inspection and manual maintenance. */
+    get log(): SyncOutbox;
+    /** The shadow store holding last-known upstream state — for diagnostics and reseeding. */
+    get baseline(): SyncShadow;
+    /**
+     * Installs capture triggers, backfills existing documents if this replicator
+     * has never run, and starts streaming changes upstream.
+     *
+     * Resolves once replication is *running*, not once it has caught up — use
+     * {@link SyncReplicator.waitForDrain} for that.
+     */
+    start(): Promise<void>;
+    /**
+     * Stops replication. Capture triggers stay installed, so changes made while
+     * stopped are still recorded and picked up on the next `start()`.
+     *
+     * @param options.flush Drain everything pending before stopping. Defaults to `false`.
+     */
+    stop(options?: {
+        flush?: boolean;
+    }): Promise<void>;
+    /**
+     * Nudges the replicator to check the outbox now instead of waiting for the
+     * next poll. Called by the client after local writes so replication latency
+     * is bounded by the upstream round trip, not the poll interval.
+     */
+    notify(): void;
+    /**
+     * Resolves once every change written *before this call* has reached the
+     * upstream. Rejects if replication stops with an error.
+     *
+     * The target is pinned to the outbox position at call time rather than
+     * "outbox is empty" — otherwise a concurrent writer could keep the outbox
+     * non-empty forever, and, worse, a `drained` event from a scan that began
+     * before the caller's own write would resolve it too early.
+     */
+    waitForDrain(): Promise<void>;
+    /** Current replication progress. */
+    status(): Promise<SyncStatus>;
+    /** Changes permanently rejected upstream. */
+    deadLetters(limit?: number): Promise<SyncDeadLetter[]>;
+    private pending;
+    /** `null` means "every collection"; an array restricts the outbox query. */
+    private collectionFilter;
+    /**
+     * Discovers collections to watch and installs their triggers.
+     *
+     * Re-run periodically so collections created after `start()` join replication
+     * without a restart.
+     */
+    private refreshCollections;
+    /**
+     * Seeds the upstream with documents that existed before replication started.
+     *
+     * The checkpoint is pinned *before* the scan begins, so a write racing the
+     * scan is either seen by the scan, or captured in the outbox above the
+     * checkpoint, or both — and "both" is harmless because upserts are idempotent.
+     */
+    private backfill;
+    /** The replication loop: read, coalesce, apply, checkpoint, repeat. */
+    private run;
+    /**
+     * Applies one batch.
+     * @returns `true` if there was work to do, `false` if the outbox was empty.
+     */
+    private drainOnce;
+    /** Acknowledges up to `id` and prunes rows no replicator needs any more. */
+    private advanceTo;
+    /**
+     * Collapses a run of changes into one operation per document.
+     *
+     * Records are in ascending outbox order, so the last one seen for a document
+     * is its current state — an upsert of the newest revision, or a delete.
+     */
+    private coalesce;
+    /**
+     * Turns coalesced records into upstream operations, attaching the base version and
+     * minimal diff from the shadow.
+     *
+     * Shadows load per collection in one query rather than per document, so a batch of
+     * 500 changes costs one extra read per collection, not 500.
+     */
+    private buildOperations;
+    /**
+     * Records the new upstream state for operations that landed.
+     *
+     * The post-write state is computed by applying the diff to the previous *server*
+     * document rather than by re-reading it — one fewer round trip, and it keeps the BSON
+     * values of untouched fields exactly as they were.
+     */
+    private commitShadows;
+    /**
+     * Reconciles a push that lost a race.
+     *
+     * The upstream state goes into the shadow first, so whatever happens next — a retry,
+     * or the application's own decision — is made against current reality rather than
+     * against the version that already lost.
+     */
+    private resolveConflict;
+    /**
+     * Writes the upstream version of a document into the local collection.
+     *
+     * The write trips the capture triggers and lands back in the outbox, which would
+     * normally mean pushing it straight back up. It does not, because the local row now
+     * matches the shadow exactly: the diff comes out empty and the echo is dropped in
+     * {@link SyncReplicator.buildOperations}. That is why the local copy is written from
+     * the same projection the diff compares against.
+     */
+    private adoptUpstream;
+    private fetchUpstream;
+    /** Maps an outbox record to an upstream operation, applying rename and transform. */
+    private toOperation;
+    /**
+     * Applies a batch, retrying transient failures with exponential backoff and
+     * jitter. Returns the operations the upstream rejected permanently, or `null`
+     * if the replicator was stopped before the batch landed.
+     *
+     * The checkpoint is never advanced while this is retrying, so an upstream
+     * outage simply parks the batch — the outbox absorbs the backlog.
+     */
+    private applyWithRetry;
+    private ensureConnected;
+    private recordDeadLetter;
+    /**
+     * Keeps the outbox from growing without bound during a long outage.
+     * Compaction is lossless here because replication is full-document
+     * last-write-wins: only superseded revisions are dropped.
+     */
+    private enforceOutboxLimit;
+    /** Sleeps, but returns early when `notify()` or `stop()` is called. */
+    private sleep;
+    private fail;
+    private log_;
+}