@powersync/service-module-mongodb 0.0.0-dev-20260803144812 → 0.0.0-dev-20260929095716

package/src/replication/MongoSnapshotter.ts

@@ -18,8 +18,13 @@ import { CheckpointImplementation } from './checkpoints/CheckpointImplementation
 import { createCheckpointImplementation } from './checkpoints/create-checkpoint-implementation.js';
 import { MongoManager } from './MongoManager.js';
 import { getMongoRelation } from './MongoRelation.js';
+import {
+  DEFAULT_MONGO_REPLICATION_QUERY_PROVIDER,
+  MongoReplicationQueryProvider
+} from './MongoReplicationQueryProvider.js';
+import { MongoReplicationStreamItem, openMongoReplicationStream } from './MongoReplicationStream.js';
 import { ChunkedSnapshotQuery } from './MongoSnapshotQuery.js';
-import { ChangeStreamBatch, parseChangeDocument, rawChangeStream } from './RawChangeStream.js';
+import { ChangeStreamBatch } from './RawChangeStream.js';
 import { CHECKPOINTS_COLLECTION, detectDocumentDb } from './replication-utils.js';
 import { DirectSourceRowConverter, SourceRowConverter } from './SourceRowConverter.js';
 
@@ -34,6 +39,7 @@ export interface MongoSnapshotterOptions {
   checkpointStreamId: mongo.ObjectId;
   storageHooks?: storage.StorageHooks;
   snapshotHooks?: MongoSnapshotterHooks;
+  queryProvider?: MongoReplicationQueryProvider;
 }
 
 export interface MongoSnapshotterHooks {
@@ -59,6 +65,7 @@ export class MongoSnapshotter {
   private readonly defaultDb: mongo.Db;
   private readonly syncRules: HydratedSyncConfig;
   private readonly sourceRowConverter: SourceRowConverter;
+  private readonly queryProvider: MongoReplicationQueryProvider;
   private readonly maxAwaitTimeMS: number;
   private readonly snapshotChunkLength: number;
   private readonly abortSignal: AbortSignal;
@@ -90,6 +97,7 @@ export class MongoSnapshotter {
     this.checkpointStreamId = options.checkpointStreamId;
     this.storageHooks = options.storageHooks;
     this.snapshotHooks = options.snapshotHooks;
+    this.queryProvider = options.queryProvider ?? DEFAULT_MONGO_REPLICATION_QUERY_PROVIDER;
     this.changeStreamTimeout = Math.ceil(this.client.options.socketTimeoutMS * 0.9);
     this.syncRules = options.storage.getParsedSyncRules({
       defaultSchema: this.defaultDb.databaseName
@@ -116,7 +124,9 @@ export class MongoSnapshotter {
     return this.storage.storageConfig.softDeleteCurrentData;
   }
 
-  /** The active checkpoint strategy. Only valid after ensureDetected(). */
+  /**
+   * The active checkpoint strategy. Only valid after ensureDetected().
+   */
   private get checkpointImplementation(): CheckpointImplementation {
     if (this._checkpointImplementation == null) {
       throw new ServiceError(
@@ -150,6 +160,7 @@ export class MongoSnapshotter {
         );
       }
     }
+    await this.queryProvider.validateSource?.({ connectionManager: this.connections, isDocumentDb: this.isDocumentDb });
     this._checkpointImplementation = createCheckpointImplementation(this.isDocumentDb, {
       client: this.client,
       db: this.defaultDb,
@@ -212,6 +223,7 @@ export class MongoSnapshotter {
       defaultSchema: this.defaultDb.databaseName,
       storeCurrentData: false,
       skipExistingRows: true,
+      signal: this.abortSignal,
       tracer: new PerformanceTracer('MongoDB initial snapshot setup')
     });
     if (snapshotLsn == null) {
@@ -243,9 +255,7 @@ export class MongoSnapshotter {
         totalEstimatedCount: count
       });
       this.queueTable(updated);
-      this.logger.info(
-        `To replicate: ${updated.qualifiedName}: ${updated.snapshotStatus?.replicatedCount}/~${updated.snapshotStatus?.totalEstimatedCount}`
-      );
+      this.logger.info(`To replicate: ${updated.qualifiedName} ${updated.formatSnapshotProgress()}`);
     }
   }
 
@@ -345,10 +355,10 @@ export class MongoSnapshotter {
       return;
     }
 
-    // Populate the cache _after_ initial replication, but _before_ we switch to this replication stream.
+    // Compact storage _after_ initial replication, but _before_ we switch to this replication stream.
     // Keeping snapshot_done false until this completes makes this resumable after interruption.
     // No checkpoint exists yet - storage defaults to its highest persisted op id.
-    await this.storage.populatePersistentChecksumCache({
+    await this.storage.compactInitialReplication({
       signal: this.abortSignal
     });
 
@@ -361,7 +371,8 @@ export class MongoSnapshotter {
       zeroLSN: MongoLSN.ZERO.comparable,
       defaultSchema: this.defaultDb.databaseName,
       storeCurrentData: false,
-      skipExistingRows: true
+      skipExistingRows: true,
+      signal: this.abortSignal
     });
 
     // The checkpoint here is a marker - we need to replicate up to at least this
@@ -391,6 +402,7 @@ export class MongoSnapshotter {
       storeCurrentData: false,
       skipExistingRows: true,
       hooks: this.storageHooks,
+      signal: this.abortSignal,
       tracer: new PerformanceTracer('MongoDB snapshot table')
     });
     // Get fresh table info, in case it was updated while queuing.
@@ -462,13 +474,15 @@ export class MongoSnapshotter {
     const bytesReplicatedMetric = this.metrics.getCounter(ReplicationMetric.DATA_REPLICATED_BYTES);
     const chunksReplicatedMetric = this.metrics.getCounter(ReplicationMetric.CHUNKS_REPLICATED);
 
-    const totalEstimatedCount = await this.estimatedCountNumber(table);
+    const filter = this.queryProvider.getSnapshotFilter(table);
+    const totalEstimatedCount = await this.estimatedCountNumber(table, filter);
     let at = table.snapshotStatus?.replicatedCount ?? 0;
     const collection = this.client.db(table.schema).collection(table.name);
     await using query = new ChunkedSnapshotQuery({
       collection,
       key: table.snapshotStatus?.lastKey,
-      batchSize: this.snapshotChunkLength
+      batchSize: this.snapshotChunkLength,
+      filter
     });
     if (query.lastKey != null) {
       this.logger.info(
@@ -562,7 +576,15 @@ export class MongoSnapshotter {
     return result.tables;
   }
 
-  private async estimatedCountNumber(table: storage.SourceTable): Promise<number> {
+  private async estimatedCountNumber(
+    table: storage.SourceTable,
+    filter = this.queryProvider.getSnapshotFilter(table)
+  ): Promise<number> {
+    // Collection metadata cannot estimate a filtered result. An exact count could require another
+    // expensive scan, so use the shared unknown-total sentinel and report only the replicated count.
+    if (filter != null) {
+      return -1;
+    }
     return await this.client.db(table.schema).collection(table.name).estimatedDocumentCount();
   }
 
@@ -613,7 +635,7 @@ export class MongoSnapshotter {
     this.checkpointImplementation.seedPosition(null);
     const startStreamFromLsn = await this.checkpointImplementation.createFirstBarrier();
     const filters = this.getSourceNamespaceFilters();
-    const iter = this.rawChangeStreamBatches({
+    const iter = this.openChangeStream({
       lsn: startStreamFromLsn,
       maxAwaitTimeMS: 0,
       signal: this.abortSignal,
@@ -624,7 +646,7 @@ export class MongoSnapshotter {
     let eventsSeen = 0;
     let batchesSeen = 0;
 
-    for await (const { events } of iter) {
+    for await (const item of iter) {
       if (performance.now() - startTime >= LSN_TIMEOUT_SECONDS * 1000) {
         break;
       }
@@ -632,26 +654,26 @@ export class MongoSnapshotter {
         await this.checkpointImplementation.createBatchCheckpoint();
         lastCheckpointCreated = performance.now();
       }
-      batchesSeen += 1;
-
-      for (const rawChangeDocument of events) {
-        const changeDocument = parseChangeDocument(rawChangeDocument);
-        const ns = 'ns' in changeDocument && 'coll' in changeDocument.ns ? changeDocument.ns : undefined;
-
-        if (ns?.coll == CHECKPOINTS_COLLECTION && 'documentKey' in changeDocument) {
-          const kind = this.checkpointImplementation.event.observe(changeDocument);
-          if (kind != 'own-barrier') {
-            // Standalone events still feed the implementation's coordinate via
-            // event.observe above; we only resolve on our own barrier.
-            continue;
-          }
-          // Observing our own barrier has set the coordinate (the barrier event
-          // carries the sentinel counter directly), so the LSN is ready.
-          return this.checkpointImplementation.event.lsn(changeDocument);
+      if (item.type == 'progress') {
+        batchesSeen += 1;
+        continue;
+      }
+      const changeDocument = item.event;
+      const ns = 'ns' in changeDocument && 'coll' in changeDocument.ns ? changeDocument.ns : undefined;
+
+      if (ns?.coll == CHECKPOINTS_COLLECTION && 'documentKey' in changeDocument) {
+        const kind = this.checkpointImplementation.event.observe(changeDocument);
+        if (kind != 'own-barrier') {
+          // Standalone events still feed the implementation's coordinate via
+          // event.observe above; we only resolve on our own barrier.
+          continue;
         }
-
-        eventsSeen += 1;
+        // Observing our own barrier has set the coordinate (the barrier event
+        // carries the sentinel counter directly), so the LSN is ready.
+        return this.checkpointImplementation.event.lsn(changeDocument);
       }
+
+      eventsSeen += 1;
     }
 
     // Could happen if there is a very large replication lag?
@@ -665,12 +687,13 @@ export class MongoSnapshotter {
    * Given a snapshot LSN, validate that we can read from it, by opening a change stream.
    */
   private async validateSnapshotLsn(lsn: string) {
-    const stream = this.rawChangeStreamBatches({
+    const stream = this.openChangeStream({
       lsn,
       maxAwaitTimeMS: 0,
-      filters: this.getSourceNamespaceFilters()
+      filters: this.getSourceNamespaceFilters(),
+      signal: this.abortSignal
     });
-    for await (const _batch of stream) {
+    for await (const _item of stream) {
       break;
     }
   }
@@ -719,76 +742,31 @@ export class MongoSnapshotter {
     return { $match: nsFilter, multipleDatabases };
   }
 
-  private rawChangeStreamBatches(options: {
+  private openChangeStream(options: {
     lsn: string | null;
     maxAwaitTimeMS?: number;
     batchSize?: number;
     filters: { $match: any; multipleDatabases: boolean };
     signal?: AbortSignal;
     tracer?: PerformanceTracer<'changestream'>;
-  }): AsyncIterableIterator<ChangeStreamBatch> {
-    const position = options.lsn ? this.checkpointImplementation.parseResumePosition(options.lsn) : null;
-    const startAfter = position?.startAfter ?? undefined;
-    const resumeAfter = position?.resumeAfter ?? undefined;
-
-    let fullDocument: 'required' | 'updateLookup';
-    if (this.isDocumentDb) {
-      // DocumentDB does not support changeStreamPreAndPostImages, so 'required' won't work.
-      fullDocument = 'updateLookup';
-    } else if (this.usePostImages) {
-      // 'read_only' or 'auto_configure'
-      // Configuration happens during snapshot, or when we see new
-      // collections.
-      fullDocument = 'required';
-    } else {
-      fullDocument = 'updateLookup';
-    }
-    const streamOptions: mongo.ChangeStreamOptions & mongo.Document = {
-      fullDocument
-    };
-    if (!this.isDocumentDb) {
-      // DocumentDB does not support showExpandedEvents.
-      streamOptions.showExpandedEvents = true;
-    }
-    const pipeline: mongo.Document[] = [{ $changeStream: streamOptions }, { $match: options.filters.$match }];
-    if (!this.isDocumentDb) {
-      // DocumentDB does not support $changeStreamSplitLargeEvent.
-      pipeline.push({ $changeStreamSplitLargeEvent: {} });
-    }
-
-    // Only one of these options can be supplied at a time.
-    if (resumeAfter) {
-      streamOptions.resumeAfter = resumeAfter;
-    } else if (startAfter != null) {
-      // Legacy: We don't persist lsns without resumeTokens anymore, but we do still handle the
-      // case if we have an old one. The sentinel implementation never produces a startAfter,
-      // and a fresh DocumentDB stream opens from "now" with neither option set.
-      streamOptions.startAtOperationTime = startAfter;
-    }
-
-    let watchDb: mongo.Db;
-    if (this.isDocumentDb || options.filters.multipleDatabases) {
-      // DocumentDB only supports cluster-level change streams.
-      // Requires readAnyDatabase@admin on Atlas.
-      watchDb = this.client.db('admin');
-      streamOptions.allChangesForCluster = true;
-    } else {
-      // Same general result, but requires less permissions than the above
-      watchDb = this.defaultDb;
-    }
-
-    const maxAwaitTimeMS = options.maxAwaitTimeMS ?? this.maxAwaitTimeMS;
-
-    return rawChangeStream(watchDb, pipeline, {
-      batchSize: options.batchSize ?? this.snapshotChunkLength,
-      maxAwaitTimeMS,
-      // maxAwaitTimeMS can be 0 for probe-style streams that do not want an idle wait.
-      // In that case there is no client-side wait to emulate for DocumentDB.
-      clientSideMaxAwaitTimeMS: this.isDocumentDb && maxAwaitTimeMS > 0,
-      maxTimeMS: this.changeStreamTimeout,
-      signal: options.signal,
-      logger: this.logger,
-      tracer: options.tracer
+    onBatch?: (batch: ChangeStreamBatch) => Disposable | void;
+  }): AsyncIterableIterator<MongoReplicationStreamItem> {
+    return openMongoReplicationStream({
+      db: this.defaultDb,
+      queryProvider: this.queryProvider,
+      namespaceFilter: options.filters,
+      isDocumentDb: this.isDocumentDb,
+      usePostImages: this.usePostImages,
+      position: options.lsn ? this.checkpointImplementation.parseResumePosition(options.lsn) : null,
+      onBatch: options.onBatch,
+      options: {
+        batchSize: options.batchSize ?? this.snapshotChunkLength,
+        maxAwaitTimeMS: options.maxAwaitTimeMS ?? this.maxAwaitTimeMS,
+        maxTimeMS: this.changeStreamTimeout,
+        signal: options.signal,
+        logger: this.logger,
+        tracer: options.tracer
+      }
     });
   }
 

package/src/replication/RawChangeStream.ts

@@ -6,14 +6,8 @@ import {
   ReplicationAssertionError
 } from '@powersync/lib-services-framework';
 import { PerformanceTracer } from '@powersync/service-core';
-import { performance } from 'node:perf_hooks';
-import { setTimeout as delay } from 'node:timers/promises';
 import { ChangeStreamInvalidatedError } from './ChangeStream.js';
 
-// Keep the DocumentDB idle-poll workaround from adding the full maxAwaitTimeMS
-// as local latency when an update arrives just after an empty batch.
-const CLIENT_SIDE_MAX_AWAIT_TIME_MS_DELAY_CAP_MS = 1_000;
-
 export interface RawChangeStreamOptions {
   signal?: AbortSignal;
 
@@ -21,21 +15,12 @@ export interface RawChangeStreamOptions {
    * How long to wait for new data per batch (max time for long-polling).
    * This is sent as maxTimeMS for the getMore command.
    *
-   * A value of 0 is allowed for probe-style streams that do not want an idle
-   * wait; in that case PowerSync also skips the local empty-batch delay.
+   * A value of 0 removes the explicit await limit and leaves the server's
+   * default awaitData behavior in effect; it does not make getMore return
+   * immediately. Snapshot probes use 0 for this purpose.
    */
   maxAwaitTimeMS: number;
 
-  /**
-   * Also enforce maxAwaitTimeMS on the client for empty getMore batches.
-   *
-   * Azure DocumentDB currently returns idle getMore calls before maxTimeMS. When
-   * this is enabled, empty batches are delayed locally (capped at 1s) to avoid
-   * tight polling. We still send maxTimeMS so this remains compatible with
-   * servers that handle maxAwaitTimeMS correctly.
-   */
-  clientSideMaxAwaitTimeMS?: boolean;
-
   /**
    * Timeout for the initial aggregate command.
    */
@@ -230,17 +215,12 @@ async function* rawChangeStreamInner(
       options.signal?.throwIfAborted();
 
       using commandSpan = options.tracer?.span('changestream', 'getmore');
-      const getMoreStartedAt = performance.now();
       const getMoreCommand: mongo.Document = {
         getMore: cursorId,
         collection: nsCollection,
         batchSize: batchSizer.next(),
         maxTimeMS: options.maxAwaitTimeMS
       };
-      // Azure DocumentDB currently returns empty getMore batches before
-      // maxTimeMS expires. Keep maxTimeMS for forward compatibility with the
-      // server-side behavior, and when client-side mode is enabled, enforce the
-      // capped idle wait locally for empty batches below.
       const getMoreResult: mongo.Document = await db.command(getMoreCommand, { session, raw: true }).catch((e) => {
         if (isMongoServerError(e) && e.codeName == 'CursorKilled') {
           // This may be due to the killCursors command issued when aborting.
@@ -268,13 +248,6 @@ async function* rawChangeStreamInner(
         // postBatchResumeToken is returned in MongoDB 4.0.7 and later, and we support 6.0+
         throw new ReplicationAssertionError(`postBatchResumeToken from aggregate response`);
       }
-      if (options.clientSideMaxAwaitTimeMS && nextBatch.length == 0) {
-        const remainingMaxAwaitTimeMS = Math.ceil(options.maxAwaitTimeMS - (performance.now() - getMoreStartedAt));
-        if (remainingMaxAwaitTimeMS > 0) {
-          const clientSideDelayMs = Math.min(remainingMaxAwaitTimeMS, CLIENT_SIDE_MAX_AWAIT_TIME_MS_DELAY_CAP_MS);
-          await delay(clientSideDelayMs, undefined, { signal: options.signal });
-        }
-      }
       yield {
         events: nextBatch,
         resumeToken: cursor.postBatchResumeToken,
@@ -391,7 +364,7 @@ type MapRawDocument<T> = T extends unknown ? { [K in keyof T]: Rawify<T[K]> } :
 export type ProjectedChangeStreamDocument =
   | Omit<mongo.ChangeStreamDropDocument, 'wallTime' | 'collectionUUID'>
   | Omit<mongo.ChangeStreamRenameDocument, 'wallTime'>
-  | Omit<mongo.ChangeStreamDeleteDocument<Buffer>, 'wallTime'>
+  | Omit<mongo.ChangeStreamDeleteDocument<Buffer>, 'wallTime' | 'collectionUUID'>
   | Omit<mongo.ChangeStreamInsertDocument<Buffer>, 'wallTime'>
   | Omit<mongo.ChangeStreamUpdateDocument<Buffer>, 'wallTime' | 'updateDescription'>
   | Omit<mongo.ChangeStreamReplaceDocument<Buffer>, 'wallTime'>;
@@ -459,7 +432,7 @@ export function mapChangeStreamError(e: unknown) {
   } else if (
     isMongoServerError(e) &&
     e.codeName == 'NoMatchingDocument' &&
-    e.errmsg?.includes('post-image was not found')
+    (e.errmsg?.includes('post-image was not found') || e.errmsg?.includes('pre-image was not found'))
   ) {
     throw new ChangeStreamInvalidatedError(e.errmsg, e);
   } else if (isMongoServerError(e) && e.hasErrorLabel('NonResumableChangeStreamError')) {

package/src/replication/SourceRowConverter.ts

@@ -1,5 +1,5 @@
 import { mongo } from '@powersync/lib-service-mongodb';
-import { applyRowContext, CompatibilityContext, SqliteRow } from '@powersync/service-sync-rules';
+import { applyRowContext, CompatibilityContext, CompatibilityOption, SqliteRow } from '@powersync/service-sync-rules';
 import { bufferToSqlite, DateRenderMode, getDateRenderMode, parseDocumentId } from './bufferToSqlite.js';
 import { constructAfterRecord } from './MongoRelation.js';
 
@@ -46,13 +46,15 @@ export class LegacySourceRowConverter implements SourceRowConverter {
 
 export class DirectSourceRowConverter implements SourceRowConverter {
   private readonly dateRenderMode: DateRenderMode;
+  private readonly fixedBooleansInJson: boolean;
 
   constructor(compatibilityContext: CompatibilityContext) {
     this.dateRenderMode = getDateRenderMode(compatibilityContext);
+    this.fixedBooleansInJson = compatibilityContext.isEnabled(CompatibilityOption.fixedBooleanInJson);
   }
 
   rawToSqliteRow(source: Buffer): { row: SqliteRow; replicaId: any } {
-    const row = bufferToSqlite(source, this.dateRenderMode);
+    const row = bufferToSqlite(source, this.dateRenderMode, this.fixedBooleansInJson);
     const replicaId = parseDocumentId(source).id;
     return { row, replicaId };
   }

package/src/replication/bufferToSqlite.ts

@@ -80,12 +80,16 @@ const SHARED_WRITER = new JsonBufferWriter();
  *
  * @param bytes the source BSON bytes
  * @param dateRenderMode derive using getDateRenderMode(compatibilityContext)
+ * @param fixedBooleansInJson whether to serialize booleans in nested JSON as booleans, derived from compatibility
+ * context.
  *
  * @returns a SqliteRow
  */
-export function bufferToSqlite(bytes: Buffer, dateRenderMode: DateRenderMode): SqliteRow {
+export function bufferToSqlite(bytes: Buffer, dateRenderMode: DateRenderMode, fixedBooleansInJson: boolean): SqliteRow {
   const row: SqliteRow = {};
   const jsonWriter = SHARED_WRITER;
+  const options: SerializeToJsonOptions = { dateRenderMode, fixedBooleans: fixedBooleansInJson };
+
   // BSON documents are length-prefixed and null-terminated. We parse directly
   // from raw bytes, so structural validation happens here rather than in the
   // upstream BSON decoder.
@@ -112,14 +116,14 @@ export function bufferToSqlite(bytes: Buffer, dateRenderMode: DateRenderMode): S
       }
       case BSON_TYPE_ARRAY: {
         jsonWriter.reset();
-        const result = serializeNestedArrayToJson(bytes, offset, 0, jsonWriter, dateRenderMode);
+        const result = serializeNestedArrayToJson(bytes, offset, 0, jsonWriter, options);
         row[key] = jsonWriter.toString();
         offset = result.nextOffset;
         break;
       }
       case BSON_TYPE_DOCUMENT: {
         jsonWriter.reset();
-        const result = serializeNestedObjectToJson(bytes, offset, 0, jsonWriter, dateRenderMode);
+        const result = serializeNestedObjectToJson(bytes, offset, 0, jsonWriter, options);
         row[key] = jsonWriter.toString();
         offset = result.nextOffset;
         break;
@@ -195,7 +199,7 @@ export function bufferToSqlite(bytes: Buffer, dateRenderMode: DateRenderMode): S
       }
       case BSON_TYPE_CODE_WITH_SCOPE: {
         jsonWriter.reset();
-        const nextOffset = writeCodeWithScopeJson(bytes, offset, 0, jsonWriter, dateRenderMode);
+        const nextOffset = writeCodeWithScopeJson(bytes, offset, 0, jsonWriter, options);
         row[key] = jsonWriter.toString();
         offset = nextOffset;
         break;
@@ -437,12 +441,17 @@ function skipBsonValue(bytes: Buffer, offset: number, type: number) {
   }
 }
 
+interface SerializeToJsonOptions {
+  dateRenderMode: DateRenderMode;
+  fixedBooleans: boolean;
+}
+
 function serializeNestedObjectToJson(
   bytes: Buffer,
   offset: number,
   depth: number,
   writer: JsonBufferWriter,
-  dateRenderMode: DateRenderMode
+  options: SerializeToJsonOptions
 ): { nextOffset: number } {
   if (depth > NESTED_DEPTH_LIMIT) {
     throw new Error(`json nested object depth exceeds the limit of ${NESTED_DEPTH_LIMIT}`);
@@ -475,7 +484,7 @@ function serializeNestedObjectToJson(
       type,
       depth,
       writer,
-      dateRenderMode
+      options
     );
     cursor = afterValue;
     // Malformed BSON must fail fast instead of getting the parser stuck on the
@@ -499,7 +508,7 @@ function serializeNestedArrayToJson(
   offset: number,
   depth: number,
   writer: JsonBufferWriter,
-  dateRenderMode: DateRenderMode
+  options: SerializeToJsonOptions
 ): { nextOffset: number } {
   if (depth > NESTED_DEPTH_LIMIT) {
     throw new Error(`json nested object depth exceeds the limit of ${NESTED_DEPTH_LIMIT}`);
@@ -527,7 +536,7 @@ function serializeNestedArrayToJson(
       type,
       depth,
       writer,
-      dateRenderMode
+      options
     );
     cursor = afterValue;
     assertAdvanced(previousCursor, cursor);
@@ -547,7 +556,7 @@ function serializeNestedElementValue(
   type: number,
   depth: number,
   writer: JsonBufferWriter,
-  dateRenderMode: DateRenderMode
+  options: SerializeToJsonOptions
 ): { nextOffset: number; defined: boolean } {
   switch (type) {
     case BSON_TYPE_DOUBLE: // Double
@@ -555,9 +564,9 @@ function serializeNestedElementValue(
     case BSON_TYPE_STRING: // String
       return serializeNestedStringElement(bytes, offset, writer);
     case BSON_TYPE_DOCUMENT: // Embedded document
-      return serializeNestedObjectElement(bytes, offset, depth, writer, dateRenderMode);
+      return serializeNestedObjectElement(bytes, offset, depth, writer, options);
     case BSON_TYPE_ARRAY: // Array
-      return serializeNestedArrayElement(bytes, offset, depth, writer, dateRenderMode);
+      return serializeNestedArrayElement(bytes, offset, depth, writer, options);
     case BSON_TYPE_BINARY: // Binary
       return serializeNestedBinaryElement(bytes, offset, writer);
     case BSON_TYPE_UNDEFINED: // Undefined
@@ -567,11 +576,22 @@ function serializeNestedElementValue(
       writer.writeQuotedHexLower(bytes, offset, 12);
       return { nextOffset: offset + 12, defined: true };
     }
-    case BSON_TYPE_BOOLEAN: // Boolean
-      writer.writeByte(bytes[offset] ? BYTE_ONE : BYTE_ZERO);
+    case BSON_TYPE_BOOLEAN: {
+      // Boolean
+      const value = !!bytes[offset];
+
+      if (options.fixedBooleans) {
+        const str = value ? 'true' : 'false';
+
+        writer.writeAscii(str);
+      } else {
+        writer.writeByte(value ? BYTE_ONE : BYTE_ZERO);
+      }
+
       return { nextOffset: offset + 1, defined: true };
+    }
     case BSON_TYPE_UTC_DATETIME: // UTC datetime
-      return serializeNestedDateTimeElement(bytes, offset, writer, dateRenderMode);
+      return serializeNestedDateTimeElement(bytes, offset, writer, options.dateRenderMode);
     case BSON_TYPE_NULL: // Null
     case BSON_TYPE_MIN_KEY: // MinKey
     case BSON_TYPE_MAX_KEY: // MaxKey
@@ -586,7 +606,7 @@ function serializeNestedElementValue(
     case BSON_TYPE_SYMBOL: // Symbol
       return serializeNestedSymbolElement(bytes, offset, writer);
     case BSON_TYPE_CODE_WITH_SCOPE: // JavaScript code with scope
-      return serializeNestedCodeWithScopeElement(bytes, offset, depth, writer, dateRenderMode);
+      return serializeNestedCodeWithScopeElement(bytes, offset, depth, writer, options);
     case BSON_TYPE_INT32: {
       // Int32
       writer.writeAscii(String(readInt32LE(bytes, offset)));
@@ -641,9 +661,9 @@ function serializeNestedObjectElement(
   offset: number,
   depth: number,
   writer: JsonBufferWriter,
-  dateRenderMode: DateRenderMode
+  options: SerializeToJsonOptions
 ): { nextOffset: number; defined: boolean } {
-  const result = serializeNestedObjectToJson(bytes, offset, depth + 1, writer, dateRenderMode);
+  const result = serializeNestedObjectToJson(bytes, offset, depth + 1, writer, options);
   return { nextOffset: result.nextOffset, defined: true };
 }
 
@@ -652,9 +672,9 @@ function serializeNestedArrayElement(
   offset: number,
   depth: number,
   writer: JsonBufferWriter,
-  dateRenderMode: DateRenderMode
+  options: SerializeToJsonOptions
 ): { nextOffset: number; defined: boolean } {
-  const result = serializeNestedArrayToJson(bytes, offset, depth + 1, writer, dateRenderMode);
+  const result = serializeNestedArrayToJson(bytes, offset, depth + 1, writer, options);
   return { nextOffset: result.nextOffset, defined: true };
 }
 
@@ -791,14 +811,14 @@ function writeCodeWithScopeJson(
   offset: number,
   depth: number,
   writer: JsonBufferWriter,
-  dateRenderMode: DateRenderMode
+  options: SerializeToJsonOptions
 ) {
   const totalLength = readInt32LE(bytes, offset);
   const { value: code, nextOffset: afterCode } = readBsonString(bytes, offset + 4);
   writer.writeAscii('{"code":');
   writer.writeQuotedJsonString(code);
   writer.writeAscii(',"scope":');
-  serializeNestedObjectToJson(bytes, afterCode, depth + 1, writer, dateRenderMode);
+  serializeNestedObjectToJson(bytes, afterCode, depth + 1, writer, options);
   writer.writeByte(BYTE_RBRACE);
   // code_w_scope carries its own total byte length, so we trust that wrapper
   // rather than reconstructing the end position from the nested scope.
@@ -885,10 +905,10 @@ function serializeNestedCodeWithScopeElement(
   offset: number,
   depth: number,
   writer: JsonBufferWriter,
-  dateRenderMode: DateRenderMode
+  options: SerializeToJsonOptions
 ): { nextOffset: number; defined: boolean } {
   return {
-    nextOffset: writeCodeWithScopeJson(bytes, offset, depth, writer, dateRenderMode),
+    nextOffset: writeCodeWithScopeJson(bytes, offset, depth, writer, options),
     defined: true
   };
 }

package/src/replication/checkpoints/CheckpointImplementation.ts

@@ -128,7 +128,7 @@ export interface CheckpointImplementation {
    * The timestamp implementation parses the timestamp embedded in the token.
    * The sentinel implementation pairs the token with the current coordinate.
    */
-  lsnFromResumeToken(resumeToken: mongo.ResumeToken): string;
+  lsnFromResumeToken(resumeToken: mongo.ResumeToken): { lsn: string; timestamp: Date | null };
 
   /**
    * Source-side replication head for write checkpoints. The LSN passed to the

package/src/replication/checkpoints/SentinelCheckpointImplementation.ts

@@ -108,11 +108,11 @@ export class SentinelCheckpointImplementation implements CheckpointImplementatio
     );
   }
 
-  lsnFromResumeToken(resumeToken: mongo.ResumeToken): string {
+  lsnFromResumeToken(resumeToken: mongo.ResumeToken) {
     // Pair the bare token with the current coordinate. The coordinate is
     // frozen between checkpoint events, so a per-batch resume marker only
     // advances the token; that is all resumption needs (see the design doc).
-    return new SentinelLSN({ sentinel: this.position, resume_token: resumeToken }).comparable;
+    return { lsn: new SentinelLSN({ sentinel: this.position, resume_token: resumeToken }).comparable, timestamp: null };
   }
 
   async createReplicationHead<T>(callback: ReplicationHeadCallback<T>): Promise<T> {

package/src/replication/checkpoints/TimestampCheckpointImplementation.ts

@@ -67,9 +67,10 @@ export class TimestampCheckpointImplementation implements CheckpointImplementati
     );
   }
 
-  lsnFromResumeToken(resumeToken: mongo.ResumeToken): string {
+  lsnFromResumeToken(resumeToken: mongo.ResumeToken) {
     // The timestamp is embedded in the resume token.
-    return MongoLSN.fromResumeToken(resumeToken).comparable;
+    const lsn = MongoLSN.fromResumeToken(resumeToken);
+    return { lsn: lsn.comparable, timestamp: timestampToDate(lsn.timestamp) };
   }
 
   async createReplicationHead<T>(callback: ReplicationHeadCallback<T>): Promise<T> {