@powersync/service-module-mongodb 0.21.2 → 0.22.0

package/dist/replication/ChangeStreamReplicationJob.js.map

@@ -1 +1 @@
-{"version":3,"file":"ChangeStreamReplicationJob.js","sourceRoot":"","sources":["../../src/replication/ChangeStreamReplicationJob.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ChangeStreamReplicationJob.js","sourceRoot":"","sources":["../../src/replication/ChangeStreamReplicationJob.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,EAAE,YAAY,EAAE,4BAA4B,EAAE,MAAM,mBAAmB,CAAC;AAS/E,MAAM,OAAO,0BAA2B,SAAQ,WAAW,CAAC,sBAAsB;IAC/D,iBAAiB,CAA2B;IAC5C,8BAA8B,CAAmD;IAC1F,UAAU,GAAwB,IAAI,CAAC;IAE/C,YAAY,OAA0C;QACpD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC;QACnD,IAAI,CAAC,8BAA8B,GAAG,OAAO,CAAC,8BAA8B,CAAC;QAC7E,kDAAkD;QAClD,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC;IACvC,CAAC;IAED,KAAK,CAAC,OAAO;QACX,sBAAsB;IACxB,CAAC;IAED,KAAK,CAAC,SAAS;QACb,MAAM,IAAI,CAAC,UAAU,EAAE,SAAS,EAAE,CAAC;IACrC,CAAC;IAED,KAAK,CAAC,SAAS;QACb,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,aAAa,EAAE,CAAC;QAC7B,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBACzC,SAAS,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAC,EAAE;oBACrC,QAAQ,EAAE,EAAE;iBACb,CAAC,CAAC;gBAEH,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,mBAAmB,EAAE,CAAC,CAAC,CAAC;gBAC1C,IAAI,CAAC,CAAC,KAAK,IAAI,IAAI,EAAE,CAAC;oBACpB,yEAAyE;oBACzE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;gBACtC,CAAC;gBAED,IAAI,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;YAClC,CAAC;YAED,IAAI,CAAC,YAAY,4BAA4B,EAAE,CAAC;gBAC9C,0DAA0D;gBAC1D,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,kBAAkB,CAAC,IAAI,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC;YAC1F,CAAC;YAED,4FAA4F;QAC9F,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,eAAe,CAAC,KAAK,EAAE,CAAC;QAC/B,CAAC;IACH,CAAC;IAED,KAAK,CAAC,aAAa;QACjB,+DAA+D;QAC/D,gEAAgE;QAChE,uCAAuC;QACvC,MAAM,iBAAiB,GAAG,IAAI,CAAC,iBAAiB,CAAC,MAAM,EAAE,CAAC;QAC1D,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,WAAW,EAAE,gBAAgB,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,eAAe,CAAC,MAAM,EAAE,CAAC,CAAC;YAClF,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;gBACnB,OAAO;YACT,CAAC;YACD,IAAI,MAAoB,CAAC;YACzB,IAAI,CAAC;gBACH,MAAM,GAAG,IAAI,YAAY,CAAC;oBACxB,YAAY,EAAE,IAAI,CAAC,eAAe,CAAC,MAAM;oBACzC,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO;oBAC7B,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO;oBAC7B,WAAW,EAAE,iBAAiB;oBAC9B,mBAAmB,EAAE,iBAAiB,CAAC,OAAO,CAAC,0BAA0B,GAAG,KAAK;oBACjF,MAAM,EAAE,IAAI,CAAC,MAAM;oBACnB,8BAA8B,EAAE,IAAI,CAAC,8BAA8B;iBACpE,CAAC,CAAC;YACL,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,wEAAwE;gBACxE,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;gBACtC,MAAM,KAAK,CAAC;YACd,CAAC;YACD,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC;YACzB,MAAM,MAAM,CAAC,SAAS,EAAE,CAAC;QAC3B,CAAC;gBAAS,CAAC;YACT,MAAM,iBAAiB,CAAC,GAAG,EAAE,CAAC;QAChC,CAAC;IACH,CAAC;IAED,uBAAuB;QACrB,OAAO,IAAI,CAAC,UAAU,EAAE,uBAAuB,EAAE,CAAC;IACpD,CAAC;CACF"}

package/dist/replication/ChangeStreamReplicator.d.ts

@@ -1,12 +1,16 @@
 import { replication, storage } from '@powersync/service-core';
 import { ChangeStreamReplicationJob } from './ChangeStreamReplicationJob.js';
 import { ConnectionManagerFactory } from './ConnectionManagerFactory.js';
+import { MongoReplicationQueryProviderFactory } from './MongoReplicationQueryProvider.js';
 export interface ChangeStreamReplicatorOptions extends replication.AbstractReplicatorOptions {
     connectionFactory: ConnectionManagerFactory;
+    createReplicationQueryProvider?: MongoReplicationQueryProviderFactory;
 }
 export declare class ChangeStreamReplicator extends replication.AbstractReplicator<ChangeStreamReplicationJob> {
     private readonly connectionFactory;
+    private readonly createReplicationQueryProvider;
     constructor(options: ChangeStreamReplicatorOptions);
+    protected get defaultSchema(): string;
     createJob(options: replication.CreateJobOptions): ChangeStreamReplicationJob;
     cleanUp(syncRulesStorage: storage.SyncRulesBucketStorage): Promise<void>;
     stop(): Promise<void>;

package/dist/replication/ChangeStreamReplicator.js

@@ -3,9 +3,14 @@ import { MongoModule } from '../module/MongoModule.js';
 import { ChangeStreamReplicationJob } from './ChangeStreamReplicationJob.js';
 export class ChangeStreamReplicator extends replication.AbstractReplicator {
     connectionFactory;
+    createReplicationQueryProvider;
     constructor(options) {
         super(options);
         this.connectionFactory = options.connectionFactory;
+        this.createReplicationQueryProvider = options.createReplicationQueryProvider;
+    }
+    get defaultSchema() {
+        return this.connectionFactory.dbConnectionConfig.database;
     }
     createJob(options) {
         return new ChangeStreamReplicationJob({
@@ -13,6 +18,7 @@ export class ChangeStreamReplicator extends replication.AbstractReplicator {
             storage: options.storage,
             metrics: this.metrics,
             connectionFactory: this.connectionFactory,
+            createReplicationQueryProvider: this.createReplicationQueryProvider,
             lock: options.lock,
             rateLimiter: this.rateLimiter
         });

package/dist/replication/ChangeStreamReplicator.js.map

@@ -1 +1 @@
-{"version":3,"file":"ChangeStreamReplicator.js","sourceRoot":"","sources":["../../src/replication/ChangeStreamReplicator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAW,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAO7E,MAAM,OAAO,sBAAuB,SAAQ,WAAW,CAAC,kBAA8C;IACnF,iBAAiB,CAA2B;IAE7D,YAAY,OAAsC;QAChD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IACrD,CAAC;IAED,SAAS,CAAC,OAAqC;QAC7C,OAAO,IAAI,0BAA0B,CAAC;YACpC,EAAE,EAAE,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,OAAO,CAAC,mBAAmB,CAAC;YACzD,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,iBAAiB,EAAE,IAAI,CAAC,iBAAiB;YACzC,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,WAAW,EAAE,IAAI,CAAC,WAAW;SAC9B,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,gBAAgD;QAC5D,4BAA4B;IAC9B,CAAC;IAED,KAAK,CAAC,IAAI;QACR,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,MAAM,IAAI,CAAC,iBAAiB,CAAC,QAAQ,EAAE,CAAC;IAC1C,CAAC;IAED,KAAK,CAAC,cAAc;QAClB,OAAO,MAAM,WAAW,CAAC,cAAc,CAAC,IAAI,CAAC,iBAAiB,CAAC,kBAAkB,CAAC,CAAC;IACrF,CAAC;CACF"}
+{"version":3,"file":"ChangeStreamReplicator.js","sourceRoot":"","sources":["../../src/replication/ChangeStreamReplicator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAW,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAS7E,MAAM,OAAO,sBAAuB,SAAQ,WAAW,CAAC,kBAA8C;IACnF,iBAAiB,CAA2B;IAC5C,8BAA8B,CAAmD;IAElG,YAAY,OAAsC;QAChD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC;QACnD,IAAI,CAAC,8BAA8B,GAAG,OAAO,CAAC,8BAA8B,CAAC;IAC/E,CAAC;IAED,IAAc,aAAa;QACzB,OAAO,IAAI,CAAC,iBAAiB,CAAC,kBAAkB,CAAC,QAAQ,CAAC;IAC5D,CAAC;IAED,SAAS,CAAC,OAAqC;QAC7C,OAAO,IAAI,0BAA0B,CAAC;YACpC,EAAE,EAAE,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,OAAO,CAAC,mBAAmB,CAAC;YACzD,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,iBAAiB,EAAE,IAAI,CAAC,iBAAiB;YACzC,8BAA8B,EAAE,IAAI,CAAC,8BAA8B;YACnE,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,WAAW,EAAE,IAAI,CAAC,WAAW;SAC9B,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,gBAAgD;QAC5D,4BAA4B;IAC9B,CAAC;IAED,KAAK,CAAC,IAAI;QACR,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,MAAM,IAAI,CAAC,iBAAiB,CAAC,QAAQ,EAAE,CAAC;IAC1C,CAAC;IAED,KAAK,CAAC,cAAc;QAClB,OAAO,MAAM,WAAW,CAAC,cAAc,CAAC,IAAI,CAAC,iBAAiB,CAAC,kBAAkB,CAAC,CAAC;IACrF,CAAC;CACF"}

package/dist/replication/MongoReplicationQueryProvider.d.ts

@@ -0,0 +1,85 @@
+import { mongo } from '@powersync/lib-service-mongodb';
+import { SourceTable } from '@powersync/service-core';
+import { HydratedSyncConfig } from '@powersync/service-sync-rules';
+import { MongoManager } from './MongoManager.js';
+import type { MongoReplicationStreamBatch, MongoReplicationStreamContext } from './MongoReplicationStreamTypes.js';
+/**
+ * Sync config and source namespace information used to construct a provider for a replication attempt.
+ */
+export interface MongoReplicationQueryProviderContext {
+    /**
+     * Hydrated sync config from which the provider can read its connection-specific options.
+     */
+    syncConfig: HydratedSyncConfig;
+    /**
+     * Identifies the source connection whose options and tables this provider handles.
+     */
+    connectionTag: string;
+    /**
+     * MongoDB database used to resolve table references without an explicit schema.
+     */
+    defaultSchema: string;
+}
+/**
+ * Adapts snapshot selection and the stream of source changes for one replication implementation.
+ * The MongoDB module owns cursor options, namespaces, BSON parsing, large-event reassembly and durable progress.
+ */
+export interface MongoReplicationQueryProvider {
+    /**
+     * Validate source capabilities before either snapshot queries or streaming cursors are opened.
+     * Throw if required capabilities are unavailable. Both the stream and snapshotter may call this hook
+     * on the same provider, so validation must be safe to repeat.
+     */
+    validateSource?(options: {
+        connectionManager: MongoManager;
+        isDocumentDb: boolean;
+    }): Promise<void>;
+    /**
+     * Call context.open() with any additional stages/pre-image options. For filtering, pass its result
+     * to filterMongoReplicationStream({ batches, filter }) with a MongoReplicationFilter callback.
+     * The helper preserves checkpoints, DDL, batch boundaries, buffered-change flags and safe progress,
+     * counts excluded events, and closes the source iterator on failure or early exit.
+     * The default provider returns the opener's batches directly.
+     * Each invocation is independent and also serves snapshot barriers and resume validation; keep
+     * filter state local to that invocation. Snapshot selection must agree with streaming decisions.
+     */
+    openChangeStream(context: MongoReplicationStreamContext): AsyncIterableIterator<MongoReplicationStreamBatch>;
+    /**
+     * Returns an additional MongoDB find predicate for a physical source table.
+     * Return null to snapshot without an additional filter. Snapshot selection must agree with the
+     * provider's streaming rules so both paths replicate the same set of documents.
+     * Expressions can be supplied as { $expr: ... }. The snapshot query combines the filter with its
+     * _id continuation predicate and uses simple collation whenever a filter is supplied.
+     */
+    getSnapshotFilter(table: SourceTable): mongo.Filter<mongo.Document> | null;
+}
+/**
+ * Creates a provider shared by a replication attempt's change stream, snapshotter and source probes.
+ */
+export type MongoReplicationQueryProviderFactory = (context: MongoReplicationQueryProviderContext) => MongoReplicationQueryProvider;
+/**
+ * Uses the standard MongoDB reader and snapshot selection without additional filtering or event translation.
+ */
+export declare const DEFAULT_MONGO_REPLICATION_QUERY_PROVIDER: MongoReplicationQueryProvider;
+/**
+ * Places provider stages after namespace selection and before optional large-event splitting.
+ * This lets provider stages inspect complete events; the shared reader reassembles any resulting fragments.
+ */
+export declare function buildMongoChangeStreamPipeline(options: {
+    /**
+     * Shared reader options, including resume position, stream scope and requested document images.
+     */
+    streamOptions: mongo.ChangeStreamOptions & mongo.Document;
+    /**
+     * Namespace predicate restricting the stream to the selected source collections and checkpoint events.
+     */
+    namespaceMatch: mongo.Document;
+    /**
+     * Additional aggregation stages supplied by the provider, in execution order.
+     */
+    pipelineStages: mongo.Document[];
+    /**
+     * Append MongoDB's large-event split stage. Disabled for DocumentDB by the shared reader.
+     */
+    includeSplitLargeEvent: boolean;
+}): mongo.Document[];

package/dist/replication/MongoReplicationQueryProvider.js

@@ -0,0 +1,23 @@
+/**
+ * Uses the standard MongoDB reader and snapshot selection without additional filtering or event translation.
+ */
+export const DEFAULT_MONGO_REPLICATION_QUERY_PROVIDER = {
+    getSnapshotFilter: () => null,
+    openChangeStream: ({ open }) => open({})
+};
+/**
+ * Places provider stages after namespace selection and before optional large-event splitting.
+ * This lets provider stages inspect complete events; the shared reader reassembles any resulting fragments.
+ */
+export function buildMongoChangeStreamPipeline(options) {
+    const pipeline = [
+        { $changeStream: options.streamOptions },
+        { $match: options.namespaceMatch },
+        ...options.pipelineStages
+    ];
+    if (options.includeSplitLargeEvent) {
+        pipeline.push({ $changeStreamSplitLargeEvent: {} });
+    }
+    return pipeline;
+}
+//# sourceMappingURL=MongoReplicationQueryProvider.js.map

package/dist/replication/MongoReplicationQueryProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MongoReplicationQueryProvider.js","sourceRoot":"","sources":["../../src/replication/MongoReplicationQueryProvider.ts"],"names":[],"mappings":"AAgEA;;GAEG;AACH,MAAM,CAAC,MAAM,wCAAwC,GAAkC;IACrF,iBAAiB,EAAE,GAAG,EAAE,CAAC,IAAI;IAC7B,gBAAgB,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;CACzC,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,8BAA8B,CAAC,OAiB9C;IACC,MAAM,QAAQ,GAAqB;QACjC,EAAE,aAAa,EAAE,OAAO,CAAC,aAAa,EAAE;QACxC,EAAE,MAAM,EAAE,OAAO,CAAC,cAAc,EAAE;QAClC,GAAG,OAAO,CAAC,cAAc;KAC1B,CAAC;IAEF,IAAI,OAAO,CAAC,sBAAsB,EAAE,CAAC;QACnC,QAAQ,CAAC,IAAI,CAAC,EAAE,4BAA4B,EAAE,EAAE,EAAE,CAAC,CAAC;IACtD,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/replication/MongoReplicationStream.d.ts

@@ -0,0 +1,74 @@
+import { mongo } from '@powersync/lib-service-mongodb';
+import { MongoReplicationQueryProvider } from './MongoReplicationQueryProvider.js';
+import { MongoReplicationFilterOptions, MongoReplicationParserOptions, MongoReplicationStreamBatch, MongoReplicationStreamBatchMetadata, MongoReplicationStreamChange, RawMongoReplicationStreamBatch } from './MongoReplicationStreamTypes.js';
+import { ChangeStreamBatch, ProjectedChangeStreamDocument, RawChangeStreamOptions } from './RawChangeStream.js';
+/**
+ * Wraps changes with a single-use iterator. Caches the token and metadata after successful exhaustion.
+ */
+export declare function createMongoReplicationStreamBatch({ events, resolveResumeToken, resolveMetadata }: {
+    /**
+     * Complete changes, optionally produced by a lazy parsing or filtering generator.
+     */
+    events: Iterable<MongoReplicationStreamChange>;
+    /**
+     * Compute a safe resume token once after successful exhaustion, using the final parser state.
+     */
+    resolveResumeToken: () => mongo.ResumeToken | undefined;
+    /**
+     * Compute this batch's final statistics after exhaustion. Defaults to no filtering.
+     */
+    resolveMetadata?: () => MongoReplicationStreamBatchMetadata;
+}): MongoReplicationStreamBatch;
+/**
+ * Filter complete data changes while retaining source batch boundaries and recovery bookkeeping.
+ * Return MongoReplicationFilterResult.KEEP to forward a change, EXCLUDE to omit it, or DELETE for an exit.
+ * Synthetic deletes retain the source identity, resume token and transaction metadata.
+ * The callback runs synchronously and lazily; failures and early exits close the underlying stream.
+ */
+export declare function filterMongoReplicationStream({ batches, filter }: MongoReplicationFilterOptions): AsyncGenerator<MongoReplicationStreamBatch>;
+/**
+ * Shared opening path for ongoing replication, snapshot barriers and resume validation.
+ */
+export declare function openMongoReplicationStream({ db, queryProvider, namespaceFilter, isDocumentDb, usePostImages, position, skipInitialTimestamp, options, onBatch }: {
+    db: mongo.Db;
+    queryProvider: MongoReplicationQueryProvider;
+    namespaceFilter: {
+        $match: mongo.Document;
+        multipleDatabases: boolean;
+    };
+    isDocumentDb: boolean;
+    usePostImages: boolean;
+    position: {
+        resumeAfter?: mongo.ResumeToken | null;
+        startAfter?: mongo.Timestamp | null;
+    } | null;
+    /**
+     * Legacy streaming positions exclude the initial timestamp; snapshot barrier probes must include it.
+     */
+    skipInitialTimestamp?: boolean;
+    options: RawChangeStreamOptions;
+    onBatch?: (batch: ChangeStreamBatch) => Disposable | void;
+}): AsyncIterableIterator<MongoReplicationStreamBatch>;
+/**
+ * Creates a stateful parser for one raw MongoDB stream. Parses BSON entries, joins split-event
+ * fragments across batches, normalizes namespaces and skips events covered by legacy timestamps.
+ * After processing a batch, callers can request safe progress. Check completion on natural EOF,
+ * not cancellation.
+ */
+export declare function createMongoReplicationStreamParser({ defaultSchema, multipleDatabases, startAfter, signal, logger }: MongoReplicationParserOptions): {
+    parse(rawEvent: Buffer): ProjectedChangeStreamDocument | null;
+    /**
+     * Returns the given transport token if it is safe to persist, or undefined while a split event is unfinished.
+     */
+    getSafeResumeToken(resumeToken: mongo.ResumeToken): unknown;
+    assertComplete(): void;
+};
+/**
+ * Wrap raw batches in lazy event iterables. BSON parsing and split-event assembly happen
+ * as consumers request events, without building a parsed array. After exhaustion, each batch retains
+ * its own resume-token result even when later batches change the parser state.
+ * Consume each batch completely before requesting the next; returning early closes the source.
+ */
+export declare function parseMongoReplicationStream({ batches, ...options }: MongoReplicationParserOptions & {
+    batches: AsyncIterable<RawMongoReplicationStreamBatch>;
+}): AsyncGenerator<MongoReplicationStreamBatch>;

package/dist/replication/MongoReplicationStream.js

@@ -0,0 +1,228 @@
+import { ReplicationAssertionError } from '@powersync/lib-services-framework';
+import { buildMongoChangeStreamPipeline } from './MongoReplicationQueryProvider.js';
+import { MongoReplicationFilterResult } from './MongoReplicationStreamTypes.js';
+import { parseChangeDocument, rawChangeStream } from './RawChangeStream.js';
+import { CHECKPOINTS_COLLECTION } from './replication-utils.js';
+/**
+ * Wraps changes with a single-use iterator. Caches the token and metadata after successful exhaustion.
+ */
+export function createMongoReplicationStreamBatch({ events, resolveResumeToken, resolveMetadata = () => ({ filteredCount: null }) }) {
+    let started = false;
+    let complete = false;
+    let resumeToken;
+    let metadata;
+    function assertComplete() {
+        // Progress is only safe to read after every event has been consumed and finalization succeeds.
+        if (!complete) {
+            throw new ReplicationAssertionError('Consume all batch events before requesting token or metadata');
+        }
+    }
+    return {
+        events: {
+            [Symbol.iterator]() {
+                // A second pass would repeat parsing/filtering against state that has already advanced.
+                if (started) {
+                    throw new ReplicationAssertionError('Batch events can only be consumed once');
+                }
+                started = true;
+                return iterate();
+            }
+        },
+        getResumeToken() {
+            assertComplete();
+            return resumeToken;
+        },
+        get metadata() {
+            assertComplete();
+            return metadata;
+        }
+    };
+    function* iterate() {
+        // Delegate lazily; an error or early return skips the finalization below.
+        yield* events;
+        // Cache this batch's final results before later batches can change the parser or filter state.
+        resumeToken = resolveResumeToken();
+        metadata = Object.freeze({ ...resolveMetadata() });
+        complete = true;
+    }
+}
+/**
+ * Filter complete data changes while retaining source batch boundaries and recovery bookkeeping.
+ * Return MongoReplicationFilterResult.KEEP to forward a change, EXCLUDE to omit it, or DELETE for an exit.
+ * Synthetic deletes retain the source identity, resume token and transaction metadata.
+ * The callback runs synchronously and lazily; failures and early exits close the underlying stream.
+ */
+export async function* filterMongoReplicationStream({ batches, filter }) {
+    for await (const sourceBatch of batches) {
+        let filteredCount = 0;
+        const batch = createMongoReplicationStreamBatch({
+            events: filterEvents(),
+            resolveResumeToken: () => sourceBatch.getResumeToken(),
+            resolveMetadata: () => ({ filteredCount: (sourceBatch.metadata.filteredCount ?? 0) + filteredCount })
+        });
+        yield batch;
+        // Assert that the consumer exhausted this batch before requesting the next one, even if every event
+        // was filtered out. The token value is unused; getResumeToken() throws if consumption is incomplete.
+        batch.getResumeToken();
+        function* filterEvents() {
+            for (const change of sourceBatch.events) {
+                const { event } = change;
+                if ((event.operationType != 'insert' &&
+                    event.operationType != 'update' &&
+                    event.operationType != 'replace' &&
+                    event.operationType != 'delete') ||
+                    event.ns.coll == CHECKPOINTS_COLLECTION) {
+                    yield change;
+                    continue;
+                }
+                const result = filter(event);
+                if (result == MongoReplicationFilterResult.EXCLUDE) {
+                    filteredCount++;
+                }
+                else if (result == MongoReplicationFilterResult.DELETE) {
+                    yield { ...change, event: { ...event, operationType: 'delete' } };
+                }
+                else {
+                    yield change;
+                }
+            }
+        }
+    }
+}
+/**
+ * Shared opening path for ongoing replication, snapshot barriers and resume validation.
+ */
+export function openMongoReplicationStream({ db, queryProvider, namespaceFilter, isDocumentDb, usePostImages, position, skipInitialTimestamp = false, options, onBatch }) {
+    const parsing = {
+        defaultSchema: db.databaseName,
+        multipleDatabases: namespaceFilter.multipleDatabases,
+        startAfter: skipInitialTimestamp && position?.resumeAfter == null ? position?.startAfter : undefined,
+        signal: options.signal,
+        logger: options.logger
+    };
+    const openRaw = async function* ({ pipelineStages = [], imageOptions = {} }) {
+        const clusterScope = isDocumentDb || namespaceFilter.multipleDatabases;
+        const streamOptions = {
+            ...imageOptions,
+            fullDocument: !isDocumentDb && usePostImages ? 'required' : 'updateLookup',
+            ...(!isDocumentDb ? { showExpandedEvents: true } : {}),
+            ...(clusterScope ? { allChangesForCluster: true } : {})
+        };
+        // Only one resume option is legal. Legacy MongoDB snapshot positions may contain just a timestamp;
+        // a fresh DocumentDB stream has neither and opens from now.
+        if (position?.resumeAfter != null) {
+            streamOptions.resumeAfter = position.resumeAfter;
+        }
+        else if (position?.startAfter != null) {
+            streamOptions.startAtOperationTime = position.startAfter;
+        }
+        const pipeline = buildMongoChangeStreamPipeline({
+            streamOptions,
+            namespaceMatch: namespaceFilter.$match,
+            pipelineStages,
+            includeSplitLargeEvent: !isDocumentDb
+        });
+        for await (const batch of rawChangeStream(clusterScope ? db.client.db('admin') : db, pipeline, options)) {
+            options.signal?.throwIfAborted();
+            using batchScope = onBatch?.(batch) || undefined;
+            yield { events: batch.events, resumeToken: batch.resumeToken };
+        }
+    };
+    return queryProvider.openChangeStream({
+        open: (options) => parseMongoReplicationStream({ batches: openRaw(options), ...parsing })
+    });
+}
+/**
+ * Creates a stateful parser for one raw MongoDB stream. Parses BSON entries, joins split-event
+ * fragments across batches, normalizes namespaces and skips events covered by legacy timestamps.
+ * After processing a batch, callers can request safe progress. Check completion on natural EOF,
+ * not cancellation.
+ */
+export function createMongoReplicationStreamParser({ defaultSchema, multipleDatabases, startAfter, signal, logger }) {
+    let splitDocument = null;
+    let flexDbNameWorkaroundLogged = false;
+    return {
+        parse(rawEvent) {
+            signal?.throwIfAborted();
+            let event = parseChangeDocument(rawEvent);
+            const fragment = event.splitEvent;
+            if (fragment != null) {
+                // A retry can resume after a received fragment inside the raw reader. Keep the partial event in
+                // memory across batches/retries, but never expose its token as a durable recovery boundary.
+                const expectedFragment = splitDocument == null ? 1 : splitDocument.splitEvent.fragment + 1;
+                if (fragment.fragment != expectedFragment ||
+                    fragment.fragment > fragment.of ||
+                    (splitDocument != null && fragment.of != splitDocument.splitEvent.of)) {
+                    throw new ReplicationAssertionError(`Unexpected splitEvent: ${JSON.stringify(fragment)}`);
+                }
+                splitDocument = splitDocument == null ? event : Object.assign(splitDocument, event);
+                if (fragment.fragment != fragment.of) {
+                    return null;
+                }
+                event = splitDocument;
+                splitDocument = null;
+            }
+            else if (splitDocument != null) {
+                throw new ReplicationAssertionError(`Incomplete splitEvent: ${JSON.stringify(splitDocument.splitEvent)}`);
+            }
+            if (startAfter != null && event.clusterTime?.lte(startAfter)) {
+                return null;
+            }
+            if (!multipleDatabases &&
+                'ns' in event &&
+                event.ns.db != defaultSchema &&
+                event.ns.db.endsWith(`_${defaultSchema}`)) {
+                // Atlas Flex can prefix the database name on events recorded while replication was paused.
+                // Normalize before adapters inspect namespaces, just as the ordinary replication loop does.
+                const originalDatabase = event.ns.db;
+                event.ns.db = defaultSchema;
+                if (!flexDbNameWorkaroundLogged) {
+                    flexDbNameWorkaroundLogged = true;
+                    logger?.warn(`Incorrect DB name in change stream: ${originalDatabase}. Changed to ${defaultSchema}.`);
+                }
+            }
+            return event;
+        },
+        /**
+         * Returns the given transport token if it is safe to persist, or undefined while a split event is unfinished.
+         */
+        getSafeResumeToken(resumeToken) {
+            return splitDocument == null ? resumeToken : undefined;
+        },
+        assertComplete() {
+            if (splitDocument != null) {
+                throw new ReplicationAssertionError(`Incomplete splitEvent: ${JSON.stringify(splitDocument.splitEvent)}`);
+            }
+        }
+    };
+}
+/**
+ * Wrap raw batches in lazy event iterables. BSON parsing and split-event assembly happen
+ * as consumers request events, without building a parsed array. After exhaustion, each batch retains
+ * its own resume-token result even when later batches change the parser state.
+ * Consume each batch completely before requesting the next; returning early closes the source.
+ */
+export async function* parseMongoReplicationStream({ batches, ...options }) {
+    const parser = createMongoReplicationStreamParser(options);
+    for await (const sourceBatch of batches) {
+        options.signal?.throwIfAborted();
+        const batch = createMongoReplicationStreamBatch({
+            events: parseEvents(sourceBatch.events),
+            resolveResumeToken: () => parser.getSafeResumeToken(sourceBatch.resumeToken)
+        });
+        yield batch;
+        // Split-event state is shared across batches, so the consumer must finish this one before the next is read.
+        // This also covers empty batches.
+        batch.getResumeToken();
+    }
+    parser.assertComplete();
+    function* parseEvents(rawEvents) {
+        for (let index = 0; index < rawEvents.length; index++) {
+            const event = parser.parse(rawEvents[index]);
+            if (event != null) {
+                yield { event, hasBufferedChanges: index < rawEvents.length - 1 };
+            }
+        }
+    }
+}
+//# sourceMappingURL=MongoReplicationStream.js.map

package/dist/replication/MongoReplicationStream.js.map

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

package/dist/replication/MongoReplicationStreamTypes.d.ts

@@ -0,0 +1,157 @@
+import type { mongo } from '@powersync/lib-service-mongodb';
+import type { Logger } from '@powersync/lib-services-framework';
+import type { ProjectedChangeStreamDocument } from './RawChangeStream.js';
+/**
+ * An unparsed MongoDB response batch. Consumers parse its entries incrementally and retain unfinished
+ * split events across batches before deciding whether its resume token is safe to persist.
+ */
+export interface RawMongoReplicationStreamBatch {
+    /**
+     * Original BSON entries in source order, including possible split-event fragments.
+     */
+    events: Buffer[];
+    /**
+     * Transport position after this batch. It may cover an incomplete event and is not yet safe progress.
+     */
+    resumeToken: mongo.ResumeToken;
+}
+/**
+ * A complete event and its position within the original source batch.
+ */
+export interface MongoReplicationStreamChange {
+    event: ProjectedChangeStreamDocument;
+    /**
+     * MongoDB returned more entries after this event, even if a provider later excludes them or the
+     * parser retains them as unfinished split fragments. For [checkpoint, excluded change], preserve
+     * true on the checkpoint so ChangeStream groups commits instead of treating it as caught up.
+     * Providers must preserve this value when forwarding or transforming events.
+     */
+    hasBufferedChanges: boolean;
+}
+/**
+ * Statistics for one fully consumed batch, independent of whether its resume token is safe.
+ */
+export interface MongoReplicationStreamBatchMetadata {
+    /**
+     * Complete events excluded from this batch. Null means no filtering was applied; zero means
+     * filtering was applied but no events were excluded. Counts do not carry across batches.
+     */
+    readonly filteredCount: number | null;
+}
+/**
+ * A single-use batch of complete events, parsed or filtered lazily as the consumer iterates.
+ * Exhaust events before reading its resume token, metadata or the next batch.
+ */
+export interface MongoReplicationStreamBatch {
+    /**
+     * Complete changes in source order, parsed or filtered lazily during synchronous iteration.
+     * Consume once and fully. It may be empty after filtering or while assembling a split event.
+     */
+    events: Iterable<MongoReplicationStreamChange>;
+    /**
+     * Returns the safe resume token after events are fully consumed, or undefined while a split event
+     * is unfinished. Throws before exhaustion. The result remains stable after later batches.
+     */
+    getResumeToken(): mongo.ResumeToken | undefined;
+    /**
+     * Final statistics for this batch, available even without a safe resume token.
+     * Throws before events are fully consumed; the result is immutable and cached afterward.
+     */
+    readonly metadata: MongoReplicationStreamBatchMetadata;
+}
+/**
+ * Provider-controlled additions to the shared cursor setup. Source scope, resume position, post-image
+ * requirements and cancellation remain controlled by the MongoDB replication module.
+ */
+export interface MongoReplicationStreamOptions {
+    /**
+     * Inserted after namespace selection and before the final large-event split stage.
+     */
+    pipelineStages?: mongo.Document[];
+    /**
+     * Request pre-images without overriding the reader's post-image, resume or scope options.
+     */
+    imageOptions?: Pick<mongo.ChangeStreamOptions, 'fullDocumentBeforeChange'>;
+}
+/**
+ * Bound source opener supplied to a query provider for one stream invocation.
+ * Providers may wrap the lazy event iterables to filter or transform complete changes.
+ */
+export interface MongoReplicationStreamContext {
+    /**
+     * Open batches whose events are parsed lazily, with cursor scope, position, cancellation and
+     * accounting already bound. Each call owns independent split-event assembly and parser state.
+     * Events are complete; progress is withheld while a split event is unfinished.
+     * Close the iterator on completion, cancellation or failure (for await handles this).
+     */
+    open(options: MongoReplicationStreamOptions): AsyncIterableIterator<MongoReplicationStreamBatch>;
+}
+/**
+ * Source context for lazy parsing of raw BSON events in default and filtering providers.
+ * These options control namespace normalization, legacy timestamp skipping and cancellation; split-event
+ * state belongs to each parser instance and must not be shared between independently opened streams.
+ */
+export interface MongoReplicationParserOptions {
+    /**
+     * Expected database name when correcting Atlas Flex's prefixed namespaces in single-database mode.
+     */
+    defaultSchema: string;
+    /**
+     * Preserve database names when the stream covers multiple databases instead of normalizing them.
+     */
+    multipleDatabases: boolean;
+    /**
+     * Exclude complete events at or before this legacy resume timestamp. Leave unset for exact-token
+     * resumes, where later events can share the same timestamp, and for snapshot barrier probes.
+     */
+    startAfter?: mongo.Timestamp | null;
+    /**
+     * Abort parsing when the owning replication attempt is cancelled. Resolving a batch's progress is not
+     * interrupted, so consumers must check the signal themselves before persisting a token.
+     */
+    signal?: AbortSignal;
+    /**
+     * Receives the namespace-correction warning, at most once per parser instance.
+     */
+    logger?: Logger;
+}
+/**
+ * A complete data change eligible for filtering. Checkpoints and DDL bypass the filter.
+ */
+export type MongoReplicationDataChange = Extract<ProjectedChangeStreamDocument, {
+    operationType: 'insert' | 'update' | 'replace' | 'delete';
+}>;
+/**
+ * The action to apply to a complete data change after evaluating filter membership.
+ */
+export declare enum MongoReplicationFilterResult {
+    /**
+     * Forward the original change.
+     */
+    KEEP = "keep",
+    /**
+     * Omit the change while retaining its batch's recovery progress.
+     */
+    EXCLUDE = "exclude",
+    /**
+     * Emit a delete because the document left the filtered set.
+     */
+    DELETE = "delete"
+}
+/**
+ * Synchronously decide how to replicate a complete data change. Checkpoints and DDL bypass this callback.
+ */
+export type MongoReplicationFilter = (event: MongoReplicationDataChange) => MongoReplicationFilterResult;
+/**
+ * Source batches and membership decisions for the shared replication filter.
+ */
+export interface MongoReplicationFilterOptions {
+    /**
+     * Ordered source batches whose boundaries and recovery progress must be preserved.
+     */
+    batches: AsyncIterable<MongoReplicationStreamBatch>;
+    /**
+     * Decide whether to keep, exclude or delete each complete data change.
+     */
+    filter: MongoReplicationFilter;
+}