mongodb 6.5.0 → 6.6.0-dev.20240504.sha.2609953

package/src/cursor/abstract_cursor.ts

@@ -1,6 +1,7 @@
 import { Readable, Transform } from 'stream';
 
 import { type BSONSerializeOptions, type Document, Long, pluckBSONSerializeOptions } from '../bson';
+import { CursorResponse } from '../cmap/wire_protocol/responses';
 import {
   type AnyError,
   MongoAPIError,
@@ -20,7 +21,7 @@ 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 } from '../utils';
+import { List, type MongoDBNamespace, ns, squashError } from '../utils';
 
 /** @internal */
 const kId = Symbol('id');
@@ -109,6 +110,8 @@ export interface AbstractCursorOptions extends BSONSerializeOptions {
    */
   awaitData?: boolean;
   noCursorTimeout?: boolean;
+  /** @internal TODO(NODE-5688): make this public */
+  timeoutMS?: number;
 }
 
 /** @internal */
@@ -142,7 +145,13 @@ export abstract class AbstractCursor<
   /** @internal */
   [kNamespace]: MongoDBNamespace;
   /** @internal */
-  [kDocuments]: List<TSchema>;
+  [kDocuments]: {
+    length: number;
+    shift(bsonOptions?: any): TSchema | null;
+    clear(): void;
+    pushMany(many: Iterable<TSchema>): void;
+    push(item: TSchema): void;
+  };
   /** @internal */
   [kClient]: MongoClient;
   /** @internal */
@@ -184,6 +193,7 @@ export abstract class AbstractCursor<
           : ReadPreference.primary,
       ...pluckBSONSerializeOptions(options)
     };
+    this[kOptions].timeoutMS = options.timeoutMS;
 
     const readConcern = ReadConcern.fromOptions(options);
     if (readConcern) {
@@ -283,7 +293,7 @@ export abstract class AbstractCursor<
     const documentsToRead = Math.min(number ?? this[kDocuments].length, this[kDocuments].length);
 
     for (let count = 0; count < documentsToRead; count++) {
-      const document = this[kDocuments].shift();
+      const document = this[kDocuments].shift(this[kOptions]);
       if (document != null) {
         bufferedDocs.push(document);
       }
@@ -309,7 +319,11 @@ export abstract class AbstractCursor<
             const message =
               'Cursor returned a `null` document, but the cursor is not exhausted.  Mapping documents to `null` is not supported in the cursor transform.';
 
-            await cleanupCursor(this, { needsToEmitClosed: true }).catch(() => null);
+            try {
+              await cleanupCursor(this, { needsToEmitClosed: true });
+            } catch (error) {
+              squashError(error);
+            }
 
             throw new MongoAPIError(message);
           }
@@ -327,7 +341,11 @@ export abstract class AbstractCursor<
       // 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) {
-        await this.close().catch(() => null);
+        try {
+          await this.close();
+        } catch (error) {
+          squashError(error);
+        }
       }
     }
   }
@@ -371,14 +389,7 @@ export abstract class AbstractCursor<
       return true;
     }
 
-    const doc = await next<TSchema>(this, { blocking: true, transform: false });
-
-    if (doc) {
-      this[kDocuments].unshift(doc);
-      return true;
-    }
-
-    return false;
+    return await next(this, { blocking: true, transform: false, shift: false });
   }
 
   /** Get the next available document from the cursor, returns null if no more documents are available. */
@@ -387,7 +398,7 @@ export abstract class AbstractCursor<
       throw new MongoCursorExhaustedError();
     }
 
-    return next(this, { blocking: true, transform: true });
+    return await next(this, { blocking: true, transform: true, shift: true });
   }
 
   /**
@@ -398,7 +409,7 @@ export abstract class AbstractCursor<
       throw new MongoCursorExhaustedError();
     }
 
-    return next(this, { blocking: false, transform: true });
+    return await next(this, { blocking: false, transform: true, shift: true });
   }
 
   /**
@@ -605,7 +616,8 @@ export abstract class AbstractCursor<
       // We only want to end this session if we created it, and it hasn't ended yet
       if (session.explicit === false) {
         if (!session.hasEnded) {
-          session.endSession().catch(() => null);
+          // eslint-disable-next-line github/no-then
+          session.endSession().then(undefined, squashError);
         }
         this[kSession] = this.client.startSession({ owner: this, explicit: false });
       }
@@ -621,15 +633,16 @@ export abstract class AbstractCursor<
   protected abstract _initialize(session: ClientSession | undefined): Promise<ExecutionResult>;
 
   /** @internal */
-  async getMore(batchSize: number): Promise<Document | null> {
+  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
+      batchSize,
+      useCursorResponse
     });
 
-    return executeOperation(this[kClient], getMoreOperation);
+    return await executeOperation(this[kClient], getMoreOperation);
   }
 
   /**
@@ -644,7 +657,11 @@ export abstract class AbstractCursor<
       const state = await this._initialize(this[kSession]);
       const response = state.response;
       this[kServer] = state.server;
-      if (response.cursor) {
+      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'
@@ -701,13 +718,42 @@ async function next<T>(
   cursor: AbstractCursor<T>,
   {
     blocking,
-    transform
+    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<T | null> {
+): Promise<boolean | T | null> {
   if (cursor.closed) {
+    if (!shift) return false;
     return null;
   }
 
@@ -718,15 +764,19 @@ async function next<T>(
     }
 
     if (cursor[kDocuments].length !== 0) {
-      const doc = cursor[kDocuments].shift();
+      if (!shift) return true;
+      const doc = cursor[kDocuments].shift(cursor[kOptions]);
 
       if (doc != null && transform && cursor[kTransform]) {
         try {
           return cursor[kTransform](doc);
         } catch (error) {
-          // `cleanupCursorAsync` should never throw, but if it does we want to throw the original
-          // error instead.
-          await cleanupCursor(cursor, { error, needsToEmitClosed: true }).catch(() => null);
+          try {
+            await cleanupCursor(cursor, { error, needsToEmitClosed: true });
+          } catch (error) {
+            // `cleanupCursor` should never throw, squash and throw the original error
+            squashError(error);
+          }
           throw error;
         }
       }
@@ -736,9 +786,10 @@ async function next<T>(
 
     if (cursor.isDead) {
       // if the cursor is dead, we clean it up
-      // cleanupCursorAsync should never throw, but if it does it indicates a bug in the driver
+      // 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;
     }
 
@@ -747,8 +798,10 @@ async function next<T>(
 
     try {
       const response = await cursor.getMore(batchSize);
-
-      if (response) {
+      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)
@@ -760,9 +813,12 @@ async function next<T>(
         cursor[kId] = cursorId;
       }
     } catch (error) {
-      // `cleanupCursorAsync` should never throw, but if it does we want to throw the original
-      // error instead.
-      await cleanupCursor(cursor, { error }).catch(() => null);
+      try {
+        await cleanupCursor(cursor, { error, needsToEmitClosed: true });
+      } catch (error) {
+        // `cleanupCursor` should never throw, squash and throw the original error
+        squashError(error);
+      }
       throw error;
     }
 
@@ -778,10 +834,12 @@ async function next<T>(
     }
 
     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;
 }
 
@@ -802,7 +860,7 @@ async function cleanupCursor(
 
   if (error) {
     if (cursor.loadBalanced && error instanceof MongoNetworkError) {
-      return completeCleanup();
+      return await completeCleanup();
     }
   }
 
@@ -850,14 +908,16 @@ async function cleanupCursor(
   cursor[kKilled] = true;
 
   if (session.hasEnded) {
-    return completeCleanup();
+    return await completeCleanup();
   }
 
   try {
     await executeOperation(
       cursor[kClient],
       new KillCursorsOperation(cursorId, cursorNs, server, { session })
-    ).catch(() => null);
+    );
+  } catch (error) {
+    squashError(error);
   } finally {
     await completeCleanup();
   }
@@ -892,6 +952,7 @@ class ReadableCursorStream extends Readable {
   }
 
   override _destroy(error: Error | null, callback: (error?: Error | null) => void): void {
+    // eslint-disable-next-line github/no-then
     this._cursor.close().then(
       () => callback(error),
       closeError => callback(closeError)
@@ -899,12 +960,14 @@ class ReadableCursorStream extends Readable {
   }
 
   private _readNext() {
-    next(this._cursor, { blocking: true, transform: true }).then(
+    // eslint-disable-next-line github/no-then
+    next(this._cursor, { blocking: true, transform: true, shift: true }).then(
       result => {
         if (result == null) {
           this.push(null);
         } else if (this.destroyed) {
-          this._cursor.close().catch(() => null);
+          // eslint-disable-next-line github/no-then
+          this._cursor.close().then(undefined, squashError);
         } else {
           if (this.push(result)) {
             return this._readNext();
@@ -919,7 +982,8 @@ class ReadableCursorStream extends Readable {
         //       a client during iteration. Alternatively, we could do the "right" thing and
         //       propagate the error message by removing this special case.
         if (err.message.match(/server is closed/)) {
-          this._cursor.close().catch(() => null);
+          // eslint-disable-next-line github/no-then
+          this._cursor.close().then(undefined, squashError);
           return this.push(null);
         }
 

package/src/cursor/aggregation_cursor.ts

@@ -76,7 +76,7 @@ export class AggregationCursor<TSchema = any> extends AbstractCursor<TSchema> {
 
   /** Execute the explain for the cursor */
   async explain(verbosity?: ExplainVerbosityLike): Promise<Document> {
-    return executeOperation(
+    return await executeOperation(
       this.client,
       new AggregateOperation(this.namespace, this[kPipeline], {
         ...this[kOptions], // NOTE: order matters here, we may need to refine this
@@ -86,33 +86,45 @@ export class AggregationCursor<TSchema = any> extends AbstractCursor<TSchema> {
     );
   }
 
+  /** Add a stage to the aggregation pipeline
+   * @example
+   * ```
+   * const documents = await users.aggregate().addStage({ $match: { name: /Mike/ } }).toArray();
+   * ```
+   * @example
+   * ```
+   * const documents = await users.aggregate()
+   *   .addStage<{ name: string }>({ $project: { name: true } })
+   *   .toArray(); // type of documents is { name: string }[]
+   * ```
+   */
+  addStage(stage: Document): this;
+  addStage<T = Document>(stage: Document): AggregationCursor<T>;
+  addStage<T = Document>(stage: Document): AggregationCursor<T> {
+    assertUninitialized(this);
+    this[kPipeline].push(stage);
+    return this as unknown as AggregationCursor<T>;
+  }
+
   /** Add a group stage to the aggregation pipeline */
   group<T = TSchema>($group: Document): AggregationCursor<T>;
   group($group: Document): this {
-    assertUninitialized(this);
-    this[kPipeline].push({ $group });
-    return this;
+    return this.addStage({ $group });
   }
 
   /** Add a limit stage to the aggregation pipeline */
   limit($limit: number): this {
-    assertUninitialized(this);
-    this[kPipeline].push({ $limit });
-    return this;
+    return this.addStage({ $limit });
   }
 
   /** Add a match stage to the aggregation pipeline */
   match($match: Document): this {
-    assertUninitialized(this);
-    this[kPipeline].push({ $match });
-    return this;
+    return this.addStage({ $match });
   }
 
   /** Add an out stage to the aggregation pipeline */
   out($out: { db: string; coll: string } | string): this {
-    assertUninitialized(this);
-    this[kPipeline].push({ $out });
-    return this;
+    return this.addStage({ $out });
   }
 
   /**
@@ -157,50 +169,36 @@ export class AggregationCursor<TSchema = any> extends AbstractCursor<TSchema> {
    * ```
    */
   project<T extends Document = Document>($project: Document): AggregationCursor<T> {
-    assertUninitialized(this);
-    this[kPipeline].push({ $project });
-    return this as unknown as AggregationCursor<T>;
+    return this.addStage<T>({ $project });
   }
 
   /** Add a lookup stage to the aggregation pipeline */
   lookup($lookup: Document): this {
-    assertUninitialized(this);
-    this[kPipeline].push({ $lookup });
-    return this;
+    return this.addStage({ $lookup });
   }
 
   /** Add a redact stage to the aggregation pipeline */
   redact($redact: Document): this {
-    assertUninitialized(this);
-    this[kPipeline].push({ $redact });
-    return this;
+    return this.addStage({ $redact });
   }
 
   /** Add a skip stage to the aggregation pipeline */
   skip($skip: number): this {
-    assertUninitialized(this);
-    this[kPipeline].push({ $skip });
-    return this;
+    return this.addStage({ $skip });
   }
 
   /** Add a sort stage to the aggregation pipeline */
   sort($sort: Sort): this {
-    assertUninitialized(this);
-    this[kPipeline].push({ $sort });
-    return this;
+    return this.addStage({ $sort });
   }
 
   /** Add a unwind stage to the aggregation pipeline */
   unwind($unwind: Document | string): this {
-    assertUninitialized(this);
-    this[kPipeline].push({ $unwind });
-    return this;
+    return this.addStage({ $unwind });
   }
 
   /** Add a geoNear stage to the aggregation pipeline */
   geoNear($geoNear: Document): this {
-    assertUninitialized(this);
-    this[kPipeline].push({ $geoNear });
-    return this;
+    return this.addStage({ $geoNear });
   }
 }

package/src/cursor/find_cursor.ts

@@ -1,4 +1,5 @@
-import { type Document, Long } from '../bson';
+import { type Document } from '../bson';
+import { CursorResponse } from '../cmap/wire_protocol/responses';
 import { MongoInvalidArgumentError, MongoTailableCursorError } from '../error';
 import { type ExplainVerbosityLike } from '../explain';
 import type { MongoClient } from '../mongo_client';
@@ -9,7 +10,7 @@ import { FindOperation, type FindOptions } from '../operations/find';
 import type { Hint } from '../operations/operation';
 import type { ClientSession } from '../sessions';
 import { formatSort, type Sort, type SortDirection } from '../sort';
-import { emitWarningOnce, mergeOptions, type MongoDBNamespace } from '../utils';
+import { emitWarningOnce, mergeOptions, type MongoDBNamespace, squashError } from '../utils';
 import { AbstractCursor, assertUninitialized } from './abstract_cursor';
 
 /** @internal */
@@ -34,7 +35,7 @@ export class FindCursor<TSchema = any> extends AbstractCursor<TSchema> {
   /** @internal */
   [kFilter]: Document;
   /** @internal */
-  [kNumReturned]?: number;
+  [kNumReturned] = 0;
   /** @internal */
   [kBuiltOptions]: FindOptions;
 
@@ -69,7 +70,7 @@ export class FindCursor<TSchema = any> extends AbstractCursor<TSchema> {
 
   /** @internal */
   async _initialize(session: ClientSession): Promise<ExecutionResult> {
-    const findOperation = new FindOperation(undefined, this.namespace, this[kFilter], {
+    const findOperation = new FindOperation(this.namespace, this[kFilter], {
       ...this[kBuiltOptions], // NOTE: order matters here, we may need to refine this
       ...this.cursorOptions,
       session
@@ -78,7 +79,12 @@ export class FindCursor<TSchema = any> extends AbstractCursor<TSchema> {
     const response = await executeOperation(this.client, findOperation);
 
     // the response is not a cursor when `explain` is enabled
-    this[kNumReturned] = response.cursor?.firstBatch?.length;
+    if (CursorResponse.is(response)) {
+      this[kNumReturned] = response.batchSize;
+    } else {
+      // Can be an explain response, hence the ?. on everything
+      this[kNumReturned] = this[kNumReturned] + (response?.cursor?.firstBatch?.length ?? 0);
+    }
 
     // TODO: NODE-2882
     return { server: findOperation.server, session, response };
@@ -94,23 +100,29 @@ export class FindCursor<TSchema = any> extends AbstractCursor<TSchema> {
         limit && limit > 0 && numReturned + batchSize > limit ? limit - numReturned : batchSize;
 
       if (batchSize <= 0) {
-        // this is an optimization for the special case of a limit for a find command to avoid an
-        // extra getMore when the limit has been reached and the limit is a multiple of the batchSize.
-        // This is a consequence of the new query engine in 5.0 having no knowledge of the limit as it
-        // produces results for the find command.  Once a batch is filled up, it is returned and only
-        // on the subsequent getMore will the query framework consider the limit, determine the cursor
-        // is exhausted and return a cursorId of zero.
-        // instead, if we determine there are no more documents to request from the server, we preemptively
-        // close the cursor
-        await this.close().catch(() => null);
-        return { cursor: { id: Long.ZERO, nextBatch: [] } };
+        try {
+          await this.close();
+        } catch (error) {
+          squashError(error);
+          // this is an optimization for the special case of a limit for a find command to avoid an
+          // extra getMore when the limit has been reached and the limit is a multiple of the batchSize.
+          // This is a consequence of the new query engine in 5.0 having no knowledge of the limit as it
+          // produces results for the find command.  Once a batch is filled up, it is returned and only
+          // on the subsequent getMore will the query framework consider the limit, determine the cursor
+          // is exhausted and return a cursorId of zero.
+          // instead, if we determine there are no more documents to request from the server, we preemptively
+          // close the cursor
+        }
+        return CursorResponse.emptyGetMore;
       }
     }
 
-    const response = await super.getMore(batchSize);
+    const response = await super.getMore(batchSize, false);
     // TODO: wrap this in some logic to prevent it from happening if we don't need this support
-    if (response) {
-      this[kNumReturned] = this[kNumReturned] + response.cursor.nextBatch.length;
+    if (CursorResponse.is(response)) {
+      this[kNumReturned] = this[kNumReturned] + response.batchSize;
+    } else {
+      this[kNumReturned] = this[kNumReturned] + (response?.cursor?.nextBatch?.length ?? 0);
     }
 
     return response;
@@ -127,7 +139,7 @@ export class FindCursor<TSchema = any> extends AbstractCursor<TSchema> {
     if (typeof options === 'boolean') {
       throw new MongoInvalidArgumentError('Invalid first parameter to count');
     }
-    return executeOperation(
+    return await executeOperation(
       this.client,
       new CountOperation(this.namespace, this[kFilter], {
         ...this[kBuiltOptions], // NOTE: order matters here, we may need to refine this
@@ -139,9 +151,9 @@ export class FindCursor<TSchema = any> extends AbstractCursor<TSchema> {
 
   /** Execute the explain for the cursor */
   async explain(verbosity?: ExplainVerbosityLike): Promise<Document> {
-    return executeOperation(
+    return await executeOperation(
       this.client,
-      new FindOperation(undefined, this.namespace, this[kFilter], {
+      new FindOperation(this.namespace, this[kFilter], {
         ...this[kBuiltOptions], // NOTE: order matters here, we may need to refine this
         ...this.cursorOptions,
         explain: verbosity ?? true

package/src/cursor/list_search_indexes_cursor.ts

@@ -3,7 +3,7 @@ import type { AggregateOptions } from '../operations/aggregate';
 import { AggregationCursor } from './aggregation_cursor';
 
 /** @public */
-export type ListSearchIndexesOptions = AggregateOptions;
+export type ListSearchIndexesOptions = Omit<AggregateOptions, 'readConcern' | 'writeConcern'>;
 
 /** @public */
 export class ListSearchIndexesCursor extends AggregationCursor<{ name: string }> {

package/src/cursor/run_command_cursor.ts

@@ -125,9 +125,10 @@ export class RunCommandCursor extends AbstractCursor {
     const getMoreOperation = new GetMoreOperation(this.namespace, this.id!, this.server!, {
       ...this.cursorOptions,
       session: this.session,
-      ...this.getMoreOptions
+      ...this.getMoreOptions,
+      useCursorResponse: false
     });
 
-    return executeOperation(this.client, getMoreOperation);
+    return await executeOperation(this.client, getMoreOperation);
   }
 }