mongodb 6.7.0 → 6.8.0

package/src/cursor/abstract_cursor.ts

@@ -1,52 +1,43 @@
 import { Readable, Transform } from 'stream';
 
 import { type BSONSerializeOptions, type Document, Long, pluckBSONSerializeOptions } from '../bson';
-import { CursorResponse } from '../cmap/wire_protocol/responses';
+import { type CursorResponse } from '../cmap/wire_protocol/responses';
 import {
-  type AnyError,
   MongoAPIError,
   MongoCursorExhaustedError,
   MongoCursorInUseError,
   MongoInvalidArgumentError,
-  MongoNetworkError,
   MongoRuntimeError,
   MongoTailableCursorError
 } from '../error';
 import type { MongoClient } from '../mongo_client';
-import { type TODO_NODE_3286, TypedEventEmitter } from '../mongo_types';
-import { executeOperation, type ExecutionResult } from '../operations/execute_operation';
+import { TypedEventEmitter } from '../mongo_types';
+import { executeOperation } from '../operations/execute_operation';
 import { GetMoreOperation } from '../operations/get_more';
 import { KillCursorsOperation } from '../operations/kill_cursors';
 import { ReadConcern, type ReadConcernLike } from '../read_concern';
 import { ReadPreference, type ReadPreferenceLike } from '../read_preference';
 import type { Server } from '../sdam/server';
 import { ClientSession, maybeClearPinnedConnection } from '../sessions';
-import { List, type MongoDBNamespace, ns, squashError } from '../utils';
+import { type MongoDBNamespace, squashError } from '../utils';
 
-/** @internal */
-const kId = Symbol('id');
-/** @internal */
-const kDocuments = Symbol('documents');
-/** @internal */
-const kServer = Symbol('server');
-/** @internal */
-const kNamespace = Symbol('namespace');
-/** @internal */
-const kClient = Symbol('client');
-/** @internal */
-const kSession = Symbol('session');
-/** @internal */
-const kOptions = Symbol('options');
-/** @internal */
-const kTransform = Symbol('transform');
-/** @internal */
-const kInitialized = Symbol('initialized');
-/** @internal */
-const kClosed = Symbol('closed');
-/** @internal */
-const kKilled = Symbol('killed');
-/** @internal */
-const kInit = Symbol('kInit');
+/**
+ * @internal
+ * TODO(NODE-2882): A cursor's getMore commands must be run on the same server it was started on
+ * and the same session must be used for the lifetime of the cursor. This object serves to get the
+ * server and session (along with the response) out of executeOperation back to the AbstractCursor.
+ *
+ * There may be a better design for communicating these values back to the cursor, currently an operation
+ * MUST store the selected server on itself so it can be read after executeOperation has returned.
+ */
+export interface InitialCursorResponse {
+  /** The server selected for the operation */
+  server: Server;
+  /** The session used for this operation, may be implicitly created */
+  session?: ClientSession;
+  /** The raw server response for the operation */
+  response: CursorResponse;
+}
 
 /** @public */
 export const CURSOR_FLAGS = [
@@ -137,39 +128,33 @@ export abstract class AbstractCursor<
   CursorEvents extends AbstractCursorEvents = AbstractCursorEvents
 > extends TypedEventEmitter<CursorEvents> {
   /** @internal */
-  [kId]: Long | null;
+  private cursorId: Long | null;
   /** @internal */
-  [kSession]: ClientSession;
+  private cursorSession: ClientSession;
   /** @internal */
-  [kServer]?: Server;
+  private selectedServer?: Server;
   /** @internal */
-  [kNamespace]: MongoDBNamespace;
+  private cursorNamespace: MongoDBNamespace;
   /** @internal */
-  [kDocuments]: {
-    length: number;
-    shift(bsonOptions?: any): TSchema | null;
-    clear(): void;
-    pushMany(many: Iterable<TSchema>): void;
-    push(item: TSchema): void;
-  };
+  private documents: CursorResponse | null = null;
   /** @internal */
-  [kClient]: MongoClient;
+  private cursorClient: MongoClient;
   /** @internal */
-  [kTransform]?: (doc: TSchema) => any;
+  private transform?: (doc: TSchema) => any;
   /** @internal */
-  [kInitialized]: boolean;
+  private initialized: boolean;
   /** @internal */
-  [kClosed]: boolean;
+  private isClosed: boolean;
   /** @internal */
-  [kKilled]: boolean;
+  private isKilled: boolean;
   /** @internal */
-  [kOptions]: InternalAbstractCursorOptions;
+  protected readonly cursorOptions: InternalAbstractCursorOptions;
 
   /** @event */
   static readonly CLOSE = 'close' as const;
 
   /** @internal */
-  constructor(
+  protected constructor(
     client: MongoClient,
     namespace: MongoDBNamespace,
     options: AbstractCursorOptions = {}
@@ -179,121 +164,132 @@ export abstract class AbstractCursor<
     if (!client.s.isMongoClient) {
       throw new MongoRuntimeError('Cursor must be constructed with MongoClient');
     }
-    this[kClient] = client;
-    this[kNamespace] = namespace;
-    this[kId] = null;
-    this[kDocuments] = new List();
-    this[kInitialized] = false;
-    this[kClosed] = false;
-    this[kKilled] = false;
-    this[kOptions] = {
+    this.cursorClient = client;
+    this.cursorNamespace = namespace;
+    this.cursorId = null;
+    this.initialized = false;
+    this.isClosed = false;
+    this.isKilled = false;
+    this.cursorOptions = {
       readPreference:
         options.readPreference && options.readPreference instanceof ReadPreference
           ? options.readPreference
           : ReadPreference.primary,
       ...pluckBSONSerializeOptions(options)
     };
-    this[kOptions].timeoutMS = options.timeoutMS;
+    this.cursorOptions.timeoutMS = options.timeoutMS;
 
     const readConcern = ReadConcern.fromOptions(options);
     if (readConcern) {
-      this[kOptions].readConcern = readConcern;
+      this.cursorOptions.readConcern = readConcern;
     }
 
     if (typeof options.batchSize === 'number') {
-      this[kOptions].batchSize = options.batchSize;
+      this.cursorOptions.batchSize = options.batchSize;
     }
 
     // we check for undefined specifically here to allow falsy values
     // eslint-disable-next-line no-restricted-syntax
     if (options.comment !== undefined) {
-      this[kOptions].comment = options.comment;
+      this.cursorOptions.comment = options.comment;
     }
 
     if (typeof options.maxTimeMS === 'number') {
-      this[kOptions].maxTimeMS = options.maxTimeMS;
+      this.cursorOptions.maxTimeMS = options.maxTimeMS;
     }
 
     if (typeof options.maxAwaitTimeMS === 'number') {
-      this[kOptions].maxAwaitTimeMS = options.maxAwaitTimeMS;
+      this.cursorOptions.maxAwaitTimeMS = options.maxAwaitTimeMS;
     }
 
     if (options.session instanceof ClientSession) {
-      this[kSession] = options.session;
+      this.cursorSession = options.session;
     } else {
-      this[kSession] = this[kClient].startSession({ owner: this, explicit: false });
+      this.cursorSession = this.cursorClient.startSession({ owner: this, explicit: false });
     }
   }
 
+  /**
+   * The cursor has no id until it receives a response from the initial cursor creating command.
+   *
+   * It is non-zero for as long as the database has an open cursor.
+   *
+   * The initiating command may receive a zero id if the entire result is in the `firstBatch`.
+   */
   get id(): Long | undefined {
-    return this[kId] ?? undefined;
+    return this.cursorId ?? undefined;
   }
 
   /** @internal */
   get isDead() {
-    return (this[kId]?.isZero() ?? false) || this[kClosed] || this[kKilled];
+    return (this.cursorId?.isZero() ?? false) || this.isClosed || this.isKilled;
   }
 
   /** @internal */
   get client(): MongoClient {
-    return this[kClient];
+    return this.cursorClient;
   }
 
   /** @internal */
   get server(): Server | undefined {
-    return this[kServer];
+    return this.selectedServer;
   }
 
   get namespace(): MongoDBNamespace {
-    return this[kNamespace];
+    return this.cursorNamespace;
   }
 
   get readPreference(): ReadPreference {
-    return this[kOptions].readPreference;
+    return this.cursorOptions.readPreference;
   }
 
   get readConcern(): ReadConcern | undefined {
-    return this[kOptions].readConcern;
+    return this.cursorOptions.readConcern;
   }
 
   /** @internal */
   get session(): ClientSession {
-    return this[kSession];
+    return this.cursorSession;
   }
 
   set session(clientSession: ClientSession) {
-    this[kSession] = clientSession;
-  }
-
-  /** @internal */
-  get cursorOptions(): InternalAbstractCursorOptions {
-    return this[kOptions];
+    this.cursorSession = clientSession;
   }
 
+  /**
+   * The cursor is closed and all remaining locally buffered documents have been iterated.
+   */
   get closed(): boolean {
-    return this[kClosed];
+    return this.isClosed && (this.documents?.length ?? 0) === 0;
   }
 
+  /**
+   * A `killCursors` command was attempted on this cursor.
+   * This is performed if the cursor id is non zero.
+   */
   get killed(): boolean {
-    return this[kKilled];
+    return this.isKilled;
   }
 
   get loadBalanced(): boolean {
-    return !!this[kClient].topology?.loadBalanced;
+    return !!this.cursorClient.topology?.loadBalanced;
   }
 
   /** Returns current buffered documents length */
   bufferedCount(): number {
-    return this[kDocuments].length;
+    return this.documents?.length ?? 0;
   }
 
   /** Returns current buffered documents */
   readBufferedDocuments(number?: number): TSchema[] {
     const bufferedDocs: TSchema[] = [];
-    const documentsToRead = Math.min(number ?? this[kDocuments].length, this[kDocuments].length);
+    const documentsToRead = Math.min(
+      number ?? this.documents?.length ?? 0,
+      this.documents?.length ?? 0
+    );
 
     for (let count = 0; count < documentsToRead; count++) {
-      const document = this[kDocuments].shift(this[kOptions]);
+      const document = this.documents?.shift(this.cursorOptions);
       if (document != null) {
         bufferedDocs.push(document);
       }
@@ -301,46 +297,38 @@ export abstract class AbstractCursor<
 
     return bufferedDocs;
   }
-
   async *[Symbol.asyncIterator](): AsyncGenerator<TSchema, void, void> {
-    if (this.closed) {
+    if (this.isClosed) {
       return;
     }
 
     try {
       while (true) {
+        if (this.isKilled) {
+          return;
+        }
+
+        if (this.closed) {
+          return;
+        }
+
+        if (this.cursorId != null && this.isDead && (this.documents?.length ?? 0) === 0) {
+          return;
+        }
+
         const document = await this.next();
 
-        // Intentional strict null check, because users can map cursors to falsey values.
-        // We allow mapping to all values except for null.
         // eslint-disable-next-line no-restricted-syntax
         if (document === null) {
-          if (!this.closed) {
-            const message =
-              'Cursor returned a `null` document, but the cursor is not exhausted.  Mapping documents to `null` is not supported in the cursor transform.';
-
-            try {
-              await cleanupCursor(this, { needsToEmitClosed: true });
-            } catch (error) {
-              squashError(error);
-            }
-
-            throw new MongoAPIError(message);
-          }
-          break;
+          return;
         }
 
         yield document;
-
-        if (this[kId] === Long.ZERO) {
-          // Cursor exhausted
-          break;
-        }
       }
     } finally {
       // Only close the cursor if it has not already been closed. This finally clause handles
       // the case when a user would break out of a for await of loop early.
-      if (!this.closed) {
+      if (!this.isClosed) {
         try {
           await this.close();
         } catch (error) {
@@ -381,35 +369,61 @@ export abstract class AbstractCursor<
   }
 
   async hasNext(): Promise<boolean> {
-    if (this[kId] === Long.ZERO) {
+    if (this.cursorId === Long.ZERO) {
       return false;
     }
 
-    if (this[kDocuments].length !== 0) {
-      return true;
-    }
+    do {
+      if ((this.documents?.length ?? 0) !== 0) {
+        return true;
+      }
+      await this.fetchBatch();
+    } while (!this.isDead || (this.documents?.length ?? 0) !== 0);
 
-    return await next(this, { blocking: true, transform: false, shift: false });
+    return false;
   }
 
   /** Get the next available document from the cursor, returns null if no more documents are available. */
   async next(): Promise<TSchema | null> {
-    if (this[kId] === Long.ZERO) {
+    if (this.cursorId === Long.ZERO) {
       throw new MongoCursorExhaustedError();
     }
 
-    return await next(this, { blocking: true, transform: true, shift: true });
+    do {
+      const doc = this.documents?.shift(this.cursorOptions);
+      if (doc != null) {
+        if (this.transform != null) return await this.transformDocument(doc);
+        return doc;
+      }
+      await this.fetchBatch();
+    } while (!this.isDead || (this.documents?.length ?? 0) !== 0);
+
+    return null;
   }
 
   /**
    * Try to get the next available document from the cursor or `null` if an empty batch is returned
    */
   async tryNext(): Promise<TSchema | null> {
-    if (this[kId] === Long.ZERO) {
+    if (this.cursorId === Long.ZERO) {
       throw new MongoCursorExhaustedError();
     }
 
-    return await next(this, { blocking: false, transform: true, shift: true });
+    let doc = this.documents?.shift(this.cursorOptions);
+    if (doc != null) {
+      if (this.transform != null) return await this.transformDocument(doc);
+      return doc;
+    }
+
+    await this.fetchBatch();
+
+    doc = this.documents?.shift(this.cursorOptions);
+    if (doc != null) {
+      if (this.transform != null) return await this.transformDocument(doc);
+      return doc;
+    }
+
+    return null;
   }
 
   /**
@@ -433,9 +447,7 @@ export abstract class AbstractCursor<
   }
 
   async close(): Promise<void> {
-    const needsToEmitClosed = !this[kClosed];
-    this[kClosed] = true;
-    await cleanupCursor(this, { needsToEmitClosed });
+    await this.cleanup();
   }
 
   /**
@@ -459,7 +471,7 @@ export abstract class AbstractCursor<
    * @param value - The flag boolean value.
    */
   addCursorFlag(flag: CursorFlag, value: boolean): this {
-    assertUninitialized(this);
+    this.throwIfInitialized();
     if (!CURSOR_FLAGS.includes(flag)) {
       throw new MongoInvalidArgumentError(`Flag ${flag} is not one of ${CURSOR_FLAGS}`);
     }
@@ -468,7 +480,7 @@ export abstract class AbstractCursor<
       throw new MongoInvalidArgumentError(`Flag ${flag} must be a boolean value`);
     }
 
-    this[kOptions][flag] = value;
+    this.cursorOptions[flag] = value;
     return this;
   }
 
@@ -515,14 +527,14 @@ export abstract class AbstractCursor<
    * @param transform - The mapping transformation method.
    */
   map<T = any>(transform: (doc: TSchema) => T): AbstractCursor<T> {
-    assertUninitialized(this);
-    const oldTransform = this[kTransform] as (doc: TSchema) => TSchema; // TODO(NODE-3283): Improve transform typing
+    this.throwIfInitialized();
+    const oldTransform = this.transform;
     if (oldTransform) {
-      this[kTransform] = doc => {
+      this.transform = doc => {
         return transform(oldTransform(doc));
       };
     } else {
-      this[kTransform] = transform;
+      this.transform = transform;
     }
 
     return this as unknown as AbstractCursor<T>;
@@ -534,11 +546,11 @@ export abstract class AbstractCursor<
    * @param readPreference - The new read preference for the cursor.
    */
   withReadPreference(readPreference: ReadPreferenceLike): this {
-    assertUninitialized(this);
+    this.throwIfInitialized();
     if (readPreference instanceof ReadPreference) {
-      this[kOptions].readPreference = readPreference;
+      this.cursorOptions.readPreference = readPreference;
     } else if (typeof readPreference === 'string') {
-      this[kOptions].readPreference = ReadPreference.fromString(readPreference);
+      this.cursorOptions.readPreference = ReadPreference.fromString(readPreference);
     } else {
       throw new MongoInvalidArgumentError(`Invalid read preference: ${readPreference}`);
     }
@@ -552,10 +564,10 @@ export abstract class AbstractCursor<
    * @param readPreference - The new read preference for the cursor.
    */
   withReadConcern(readConcern: ReadConcernLike): this {
-    assertUninitialized(this);
+    this.throwIfInitialized();
     const resolvedReadConcern = ReadConcern.fromOptions({ readConcern });
     if (resolvedReadConcern) {
-      this[kOptions].readConcern = resolvedReadConcern;
+      this.cursorOptions.readConcern = resolvedReadConcern;
     }
 
     return this;
@@ -567,12 +579,12 @@ export abstract class AbstractCursor<
    * @param value - Number of milliseconds to wait before aborting the query.
    */
   maxTimeMS(value: number): this {
-    assertUninitialized(this);
+    this.throwIfInitialized();
     if (typeof value !== 'number') {
       throw new MongoInvalidArgumentError('Argument for maxTimeMS must be a number');
     }
 
-    this[kOptions].maxTimeMS = value;
+    this.cursorOptions.maxTimeMS = value;
     return this;
   }
 
@@ -582,8 +594,8 @@ export abstract class AbstractCursor<
    * @param value - The number of documents to return per batch. See {@link https://www.mongodb.com/docs/manual/reference/command/find/|find command documentation}.
    */
   batchSize(value: number): this {
-    assertUninitialized(this);
-    if (this[kOptions].tailable) {
+    this.throwIfInitialized();
+    if (this.cursorOptions.tailable) {
       throw new MongoTailableCursorError('Tailable cursor does not support batchSize');
     }
 
@@ -591,7 +603,7 @@ export abstract class AbstractCursor<
       throw new MongoInvalidArgumentError('Operation "batchSize" requires an integer');
     }
 
-    this[kOptions].batchSize = value;
+    this.cursorOptions.batchSize = value;
     return this;
   }
 
@@ -601,17 +613,17 @@ export abstract class AbstractCursor<
    * if the resultant data has already been retrieved by this cursor.
    */
   rewind(): void {
-    if (!this[kInitialized]) {
+    if (!this.initialized) {
       return;
     }
 
-    this[kId] = null;
-    this[kDocuments].clear();
-    this[kClosed] = false;
-    this[kKilled] = false;
-    this[kInitialized] = false;
+    this.cursorId = null;
+    this.documents?.clear();
+    this.isClosed = false;
+    this.isKilled = false;
+    this.initialized = false;
 
-    const session = this[kSession];
+    const session = this.cursorSession;
     if (session) {
       // We only want to end this session if we created it, and it hasn't ended yet
       if (session.explicit === false) {
@@ -619,7 +631,7 @@ export abstract class AbstractCursor<
           // eslint-disable-next-line github/no-then
           session.endSession().then(undefined, squashError);
         }
-        this[kSession] = this.client.startSession({ owner: this, explicit: false });
+        this.cursorSession = this.cursorClient.startSession({ owner: this, explicit: false });
       }
     }
   }
@@ -630,19 +642,34 @@ export abstract class AbstractCursor<
   abstract clone(): AbstractCursor<TSchema>;
 
   /** @internal */
-  protected abstract _initialize(session: ClientSession | undefined): Promise<ExecutionResult>;
+  protected abstract _initialize(
+    session: ClientSession | undefined
+  ): Promise<InitialCursorResponse>;
 
   /** @internal */
-  async getMore(batchSize: number, useCursorResponse = false): Promise<Document | null> {
-    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-    const getMoreOperation = new GetMoreOperation(this[kNamespace], this[kId]!, this[kServer]!, {
-      ...this[kOptions],
-      session: this[kSession],
-      batchSize,
-      useCursorResponse
-    });
+  async getMore(batchSize: number): Promise<CursorResponse> {
+    if (this.cursorId == null) {
+      throw new MongoRuntimeError(
+        'Unexpected null cursor id. A cursor creating command should have set this'
+      );
+    }
+    if (this.selectedServer == null) {
+      throw new MongoRuntimeError(
+        'Unexpected null selectedServer. A cursor creating command should have set this'
+      );
+    }
+    const getMoreOperation = new GetMoreOperation(
+      this.cursorNamespace,
+      this.cursorId,
+      this.selectedServer,
+      {
+        ...this.cursorOptions,
+        session: this.cursorSession,
+        batchSize
+      }
+    );
 
-    return await executeOperation(this[kClient], getMoreOperation);
+    return await executeOperation(this.cursorClient, getMoreOperation);
   }
 
   /**
@@ -652,169 +679,60 @@ export abstract class AbstractCursor<
    * operation.  We cannot refactor to use the abstract _initialize method without
    * a significant refactor.
    */
-  async [kInit](): Promise<void> {
+  private async cursorInit(): Promise<void> {
     try {
-      const state = await this._initialize(this[kSession]);
+      const state = await this._initialize(this.cursorSession);
       const response = state.response;
-      this[kServer] = state.server;
-      if (CursorResponse.is(response)) {
-        this[kId] = response.id;
-        if (response.ns) this[kNamespace] = response.ns;
-        this[kDocuments] = response;
-      } else if (response.cursor) {
-        // TODO(NODE-2674): Preserve int64 sent from MongoDB
-        this[kId] =
-          typeof response.cursor.id === 'number'
-            ? Long.fromNumber(response.cursor.id)
-            : typeof response.cursor.id === 'bigint'
-            ? Long.fromBigInt(response.cursor.id)
-            : response.cursor.id;
-
-        if (response.cursor.ns) {
-          this[kNamespace] = ns(response.cursor.ns);
-        }
-
-        this[kDocuments].pushMany(response.cursor.firstBatch);
-      }
-
-      // When server responses return without a cursor document, we close this cursor
-      // and return the raw server response. This is often the case for explain commands
-      // for example
-      if (this[kId] == null) {
-        this[kId] = Long.ZERO;
-        // TODO(NODE-3286): ExecutionResult needs to accept a generic parameter
-        this[kDocuments].push(state.response as TODO_NODE_3286);
-      }
-
-      // the cursor is now initialized, even if it is dead
-      this[kInitialized] = true;
+      this.selectedServer = state.server;
+      this.cursorId = response.id;
+      this.cursorNamespace = response.ns ?? this.namespace;
+      this.documents = response;
+      this.initialized = true; // the cursor is now initialized, even if it is dead
     } catch (error) {
       // the cursor is now initialized, even if an error occurred
-      this[kInitialized] = true;
-      await cleanupCursor(this, { error });
+      this.initialized = true;
+      await this.cleanup(error);
       throw error;
     }
 
     if (this.isDead) {
-      await cleanupCursor(this, undefined);
+      await this.cleanup();
     }
 
     return;
   }
-}
-
-/**
- * @param cursor - the cursor on which to call `next`
- * @param blocking - a boolean indicating whether or not the cursor should `block` until data
- *     is available.  Generally, this flag is set to `false` because if the getMore returns no documents,
- *     the cursor has been exhausted.  In certain scenarios (ChangeStreams, tailable await cursors and
- *     `tryNext`, for example) blocking is necessary because a getMore returning no documents does
- *     not indicate the end of the cursor.
- * @param transform - if true, the cursor's transform function is applied to the result document (if the transform exists)
- * @returns the next document in the cursor, or `null`.  When `blocking` is `true`, a `null` document means
- * the cursor has been exhausted.  Otherwise, it means that there is no document available in the cursor's buffer.
- */
-async function next<T>(
-  cursor: AbstractCursor<T>,
-  {
-    blocking,
-    transform,
-    shift
-  }: {
-    blocking: boolean;
-    transform: boolean;
-    shift: false;
-  }
-): Promise<boolean>;
-
-async function next<T>(
-  cursor: AbstractCursor<T>,
-  {
-    blocking,
-    transform,
-    shift
-  }: {
-    blocking: boolean;
-    transform: boolean;
-    shift: true;
-  }
-): Promise<T | null>;
-
-async function next<T>(
-  cursor: AbstractCursor<T>,
-  {
-    blocking,
-    transform,
-    shift
-  }: {
-    blocking: boolean;
-    transform: boolean;
-    shift: boolean;
-  }
-): Promise<boolean | T | null> {
-  if (cursor.closed) {
-    if (!shift) return false;
-    return null;
-  }
-
-  do {
-    if (cursor[kId] == null) {
-      // All cursors must operate within a session, one must be made implicitly if not explicitly provided
-      await cursor[kInit]();
-    }
-
-    if (cursor[kDocuments].length !== 0) {
-      if (!shift) return true;
-      const doc = cursor[kDocuments].shift(cursor[kOptions]);
-
-      if (doc != null && transform && cursor[kTransform]) {
-        try {
-          return cursor[kTransform](doc);
-        } catch (error) {
-          try {
-            await cleanupCursor(cursor, { error, needsToEmitClosed: true });
-          } catch (error) {
-            // `cleanupCursor` should never throw, squash and throw the original error
-            squashError(error);
-          }
-          throw error;
-        }
-      }
 
-      return doc;
+  /** @internal Attempt to obtain more documents */
+  private async fetchBatch(): Promise<void> {
+    if (this.isClosed) {
+      return;
     }
 
-    if (cursor.isDead) {
+    if (this.isDead) {
       // if the cursor is dead, we clean it up
       // cleanupCursor should never throw, but if it does it indicates a bug in the driver
       // and we should surface the error
-      await cleanupCursor(cursor, {});
-      if (!shift) return false;
-      return null;
+      await this.cleanup();
+      return;
+    }
+
+    if (this.cursorId == null) {
+      await this.cursorInit();
+      // If the cursor died or returned documents, return
+      if ((this.documents?.length ?? 0) !== 0 || this.isDead) return;
+      // Otherwise, run a getMore
     }
 
     // otherwise need to call getMore
-    const batchSize = cursor[kOptions].batchSize || 1000;
+    const batchSize = this.cursorOptions.batchSize || 1000;
 
     try {
-      const response = await cursor.getMore(batchSize);
-      if (CursorResponse.is(response)) {
-        cursor[kId] = response.id;
-        cursor[kDocuments] = response;
-      } else if (response) {
-        const cursorId =
-          typeof response.cursor.id === 'number'
-            ? Long.fromNumber(response.cursor.id)
-            : typeof response.cursor.id === 'bigint'
-            ? Long.fromBigInt(response.cursor.id)
-            : response.cursor.id;
-
-        cursor[kDocuments].pushMany(response.cursor.nextBatch);
-        cursor[kId] = cursorId;
-      }
+      const response = await this.getMore(batchSize);
+      this.cursorId = response.id;
+      this.documents = response;
     } catch (error) {
       try {
-        await cleanupCursor(cursor, { error, needsToEmitClosed: true });
+        await this.cleanup(error);
       } catch (error) {
         // `cleanupCursor` should never throw, squash and throw the original error
         squashError(error);
@@ -822,7 +740,7 @@ async function next<T>(
       throw error;
     }
 
-    if (cursor.isDead) {
+    if (this.isDead) {
       // If we successfully received a response from a cursor BUT the cursor indicates that it is exhausted,
       // we intentionally clean up the cursor to release its session back into the pool before the cursor
       // is iterated.  This prevents a cursor that is exhausted on the server from holding
@@ -830,103 +748,87 @@ async function next<T>(
       //
       // cleanupCursorAsync should never throw, but if it does it indicates a bug in the driver
       // and we should surface the error
-      await cleanupCursor(cursor, {});
-    }
-
-    if (cursor[kDocuments].length === 0 && blocking === false) {
-      if (!shift) return false;
-      return null;
-    }
-  } while (!cursor.isDead || cursor[kDocuments].length !== 0);
-
-  if (!shift) return false;
-  return null;
-}
-
-async function cleanupCursor(
-  cursor: AbstractCursor,
-  options: { error?: AnyError | undefined; needsToEmitClosed?: boolean } | undefined
-): Promise<void> {
-  const cursorId = cursor[kId];
-  const cursorNs = cursor[kNamespace];
-  const server = cursor[kServer];
-  const session = cursor[kSession];
-  const error = options?.error;
-
-  // Cursors only emit closed events once the client-side cursor has been exhausted fully or there
-  // was an error.  Notably, when the server returns a cursor id of 0 and a non-empty batch, we
-  // cleanup the cursor but don't emit a `close` event.
-  const needsToEmitClosed = options?.needsToEmitClosed ?? cursor[kDocuments].length === 0;
-
-  if (error) {
-    if (cursor.loadBalanced && error instanceof MongoNetworkError) {
-      return await completeCleanup();
+      await this.cleanup();
     }
   }
 
-  if (cursorId == null || server == null || cursorId.isZero() || cursorNs == null) {
-    if (needsToEmitClosed) {
-      cursor[kClosed] = true;
-      cursor[kId] = Long.ZERO;
-      cursor.emit(AbstractCursor.CLOSE);
-    }
-
-    if (session) {
-      if (session.owner === cursor) {
+  /** @internal */
+  private async cleanup(error?: Error) {
+    this.isClosed = true;
+    const session = this.cursorSession;
+    try {
+      if (
+        !this.isKilled &&
+        this.cursorId &&
+        !this.cursorId.isZero() &&
+        this.cursorNamespace &&
+        this.selectedServer &&
+        !session.hasEnded
+      ) {
+        this.isKilled = true;
+        const cursorId = this.cursorId;
+        this.cursorId = Long.ZERO;
+        await executeOperation(
+          this.cursorClient,
+          new KillCursorsOperation(cursorId, this.cursorNamespace, this.selectedServer, {
+            session
+          })
+        );
+      }
+    } catch (error) {
+      squashError(error);
+    } finally {
+      if (session?.owner === this) {
         await session.endSession({ error });
-        return;
       }
-
-      if (!session.inTransaction()) {
+      if (!session?.inTransaction()) {
         maybeClearPinnedConnection(session, { error });
       }
-    }
 
-    return;
+      this.emitClose();
+    }
   }
 
-  async function completeCleanup() {
-    if (session) {
-      if (session.owner === cursor) {
-        try {
-          await session.endSession({ error });
-        } finally {
-          cursor.emit(AbstractCursor.CLOSE);
-        }
-        return;
-      }
-
-      if (!session.inTransaction()) {
-        maybeClearPinnedConnection(session, { error });
+  /** @internal */
+  private hasEmittedClose = false;
+  /** @internal */
+  private emitClose() {
+    try {
+      if (!this.hasEmittedClose && ((this.documents?.length ?? 0) === 0 || this.isClosed)) {
+        // @ts-expect-error: CursorEvents is generic so Parameters<CursorEvents["close"]> may not be assignable to `[]`. Not sure how to require extenders do not add parameters.
+        this.emit('close');
       }
+    } finally {
+      this.hasEmittedClose = true;
     }
-
-    cursor.emit(AbstractCursor.CLOSE);
-    return;
   }
 
-  cursor[kKilled] = true;
-
-  if (session.hasEnded) {
-    return await completeCleanup();
-  }
+  /** @internal */
+  private async transformDocument(document: NonNullable<TSchema>): Promise<TSchema> {
+    if (this.transform == null) return document;
 
-  try {
-    await executeOperation(
-      cursor[kClient],
-      new KillCursorsOperation(cursorId, cursorNs, server, { session })
-    );
-  } catch (error) {
-    squashError(error);
-  } finally {
-    await completeCleanup();
+    try {
+      const transformedDocument = this.transform(document);
+      // eslint-disable-next-line no-restricted-syntax
+      if (transformedDocument === null) {
+        const TRANSFORM_TO_NULL_ERROR =
+          'Cursor returned a `null` document, but the cursor is not exhausted.  Mapping documents to `null` is not supported in the cursor transform.';
+        throw new MongoAPIError(TRANSFORM_TO_NULL_ERROR);
+      }
+      return transformedDocument;
+    } catch (transformError) {
+      try {
+        await this.close();
+      } catch (closeError) {
+        squashError(closeError);
+      }
+      throw transformError;
+    }
   }
-}
 
-/** @internal */
-export function assertUninitialized(cursor: AbstractCursor): void {
-  if (cursor[kInitialized]) {
-    throw new MongoCursorInUseError();
+  /** @internal */
+  protected throwIfInitialized() {
+    if (this.initialized) throw new MongoCursorInUseError();
   }
 }
 
@@ -960,8 +862,13 @@ class ReadableCursorStream extends Readable {
   }
 
   private _readNext() {
+    if (this._cursor.id === Long.ZERO) {
+      this.push(null);
+      return;
+    }
+
     // eslint-disable-next-line github/no-then
-    next(this._cursor, { blocking: true, transform: true, shift: true }).then(
+    this._cursor.next().then(
       result => {
         if (result == null) {
           this.push(null);