feat(NODE-6472): run findOne without cursor

src/cmap/wire_protocol/responses.ts

@@ -391,3 +391,9 @@ export class ClientBulkWriteCursorResponse extends CursorResponse {
     return this.get('writeConcernError', BSONType.object, false);
   }
 }
+
+export class ExplainResponse extends MongoDBResponse {
+  get queryPlanner() {
+    return this.get('queryPlanner', BSONType.object, false);
+  }
+}

src/collection.ts

@@ -39,7 +39,7 @@ import {
   type EstimatedDocumentCountOptions
 } from './operations/estimated_document_count';
 import { executeOperation } from './operations/execute_operation';
-import type { FindOptions } from './operations/find';
+import { type FindOptions } from './operations/find';
 import {
   FindOneAndDeleteOperation,
   type FindOneAndDeleteOptions,
@@ -48,6 +48,7 @@ import {
   FindOneAndUpdateOperation,
   type FindOneAndUpdateOptions
 } from './operations/find_and_modify';
+import { FindOneOperation, type FindOneOptions } from './operations/find_one';
 import {
   CreateIndexesOperation,
   type CreateIndexesOptions,
@@ -507,25 +508,33 @@ export class Collection<TSchema extends Document = Document> {
   async findOne(filter: Filter<TSchema>): Promise<WithId<TSchema> | null>;
   async findOne(
     filter: Filter<TSchema>,
-    options: Omit<FindOptions, 'timeoutMode'> & Abortable
+    options: Omit<FindOneOptions, 'timeoutMode'> & Abortable
   ): Promise<WithId<TSchema> | null>;
 
   // allow an override of the schema.
   async findOne<T = TSchema>(): Promise<T | null>;
   async findOne<T = TSchema>(filter: Filter<TSchema>): Promise<T | null>;
   async findOne<T = TSchema>(
     filter: Filter<TSchema>,
-    options?: Omit<FindOptions, 'timeoutMode'> & Abortable
+    options?: Omit<FindOneOptions, 'timeoutMode'> & Abortable
   ): Promise<T | null>;
 
   async findOne(
     filter: Filter<TSchema> = {},
-    options: FindOptions & Abortable = {}
+    options: Omit<FindOneOptions, ''> & Abortable = {}
   ): Promise<WithId<TSchema> | null> {
-    const cursor = this.find(filter, options).limit(-1).batchSize(1);
-    const res = await cursor.next();
-    await cursor.close();
-    return res;
+    //const cursor = this.find(filter, options).limit(-1).batchSize(1);
+    //const res = await cursor.next();
+    //await cursor.close();
+    return await executeOperation(
+      this.client,
+      new FindOneOperation(
+        this.s.db,
+        this.collectionName,
+        filter,
+        resolveOptions(this as TODO_NODE_3286, options)
+      )
+    );
   }
 
   /**

src/index.ts

@@ -529,6 +529,7 @@ export type {
   FindOneAndReplaceOptions,
   FindOneAndUpdateOptions
 } from './operations/find_and_modify';
+export type { FindOneOptions } from './operations/find_one';
 export type { IndexInformationOptions } from './operations/indexes';
 export type {
   CreateIndexesOptions,

src/operations/find.ts

@@ -142,7 +142,11 @@ export class FindOperation extends CommandOperation<CursorResponse> {
   }
 }
 
-function makeFindCommand(ns: MongoDBNamespace, filter: Document, options: FindOptions): Document {
+export function makeFindCommand(
+  ns: MongoDBNamespace,
+  filter: Document,
+  options: FindOptions
+): Document {
   const findCommand: Document = {
     find: ns.collection,
     filter
@@ -195,7 +199,13 @@ function makeFindCommand(ns: MongoDBNamespace, filter: Document, options: FindOp
 
       findCommand.singleBatch = true;
     } else {
-      findCommand.batchSize = options.batchSize;
+      if (options.batchSize === options.limit) {
+        // Spec dictates that if these are equal the batchSize should be one more than the
+        // limit to avoid leaving the cursor open.
+        findCommand.batchSize = options.batchSize + 1;
+      } else {
+        findCommand.batchSize = options.batchSize;
+      }
     }
   }
 

src/operations/find_one.ts

@@ -0,0 +1,91 @@
+import { type Db } from '..';
+import { type Document, pluckBSONSerializeOptions } from '../bson';
+import { type OnDemandDocumentDeserializeOptions } from '../cmap/wire_protocol/on_demand/document';
+import { CursorResponse, ExplainResponse } from '../cmap/wire_protocol/responses';
+import type { Server } from '../sdam/server';
+import type { ClientSession } from '../sessions';
+import { type TimeoutContext } from '../timeout';
+import { MongoDBNamespace } from '../utils';
+import { CommandOperation } from './command';
+import { type FindOptions, makeFindCommand } from './find';
+import { Aspect, defineAspects } from './operation';
+
+/** @public */
+export interface FindOneOptions extends FindOptions {
+  /** @deprecated Will be removed in the next major version. User provided value will be ignored. */
+  batchSize?: number;
+  /** @deprecated Will be removed in the next major version. User provided value will be ignored. */
+  limit?: number;
+  /** @deprecated Will be removed in the next major version. User provided value will be ignored. */
+  noCursorTimeout?: boolean;
+}
+
+/** @internal */
+export class FindOneOperation<TSchema = any> extends CommandOperation<TSchema> {
+  override options: FindOneOptions;
+  /** @internal */
+  private namespace: MongoDBNamespace;
+  /** @internal */
+  private filter: Document;
+  /** @internal */
+  protected deserializationOptions: OnDemandDocumentDeserializeOptions;
+
+  constructor(db: Db, collectionName: string, filter: Document, options: FindOneOptions = {}) {
+    super(db, options);
+    this.namespace = new MongoDBNamespace(db.databaseName, collectionName);
+    // special case passing in an ObjectId as a filter
+    this.filter = filter != null && filter._bsontype === 'ObjectId' ? { _id: filter } : filter;
+    this.options = { ...options };
+    this.deserializationOptions = {
+      ...pluckBSONSerializeOptions(options),
+      validation: {
+        utf8: options?.enableUtf8Validation === false ? false : true
+      }
+    };
+  }
+
+  override get commandName() {
+    return 'find' as const;
+  }
+
+  override async execute(
+    server: Server,
+    session: ClientSession | undefined,
+    timeoutContext: TimeoutContext
+  ): Promise<TSchema> {
+    const command: Document = makeFindCommand(this.namespace, this.filter, this.options);
+    // Explicitly set the limit to 1 and singleBatch to true for all commands, per the spec.
+    // noCursorTimeout must be unset as well as batchSize.
+    // See: https://github.com/mongodb/specifications/blob/master/source/crud/crud.md#findone-api-details
+    command.limit = 1;
+    command.singleBatch = true;
+    if (command.noCursorTimeout != null) {
+      delete command.noCursorTimeout;
+    }
+    if (command.batchSize != null) {
+      delete command.batchSize;
+    }
+
+    if (this.explain) {
+      const response = await super.executeCommand(
+        server,
+        session,
+        command,
+        timeoutContext,
+        ExplainResponse
+      );
+      return response.toObject() as TSchema;
+    } else {
+      const response = await super.executeCommand(
+        server,
+        session,
+        command,
+        timeoutContext,
+        CursorResponse
+      );
+      return response.shift(this.deserializationOptions);
+    }
+  }
+}
+
+defineAspects(FindOneOperation, [Aspect.READ_OPERATION, Aspect.RETRYABLE, Aspect.EXPLAINABLE]);

test/integration/crud/crud_api.test.ts

@@ -98,50 +98,6 @@ describe('CRUD API', function () {
       await collection.drop().catch(() => null);
       await client.close();
     });
-
-    describe('when the operation succeeds', () => {
-      it('the cursor for findOne is closed', async function () {
-        const spy = sinon.spy(Collection.prototype, 'find');
-        const result = await collection.findOne({});
-        expect(result).to.deep.equal({ _id: 1 });
-        expect(events.at(0)).to.be.instanceOf(CommandSucceededEvent);
-        expect(spy.returnValues.at(0)).to.have.property('closed', true);
-        expect(spy.returnValues.at(0)).to.have.nested.property('session.hasEnded', true);
-      });
-    });
-
-    describe('when the find operation fails', () => {
-      beforeEach(async function () {
-        const failPoint: FailPoint = {
-          configureFailPoint: 'failCommand',
-          mode: 'alwaysOn',
-          data: {
-            failCommands: ['find'],
-            // 1 == InternalError, but this value not important to the test
-            errorCode: 1
-          }
-        };
-        await client.db().admin().command(failPoint);
-      });
-
-      afterEach(async function () {
-        const failPoint: FailPoint = {
-          configureFailPoint: 'failCommand',
-          mode: 'off',
-          data: { failCommands: ['find'] }
-        };
-        await client.db().admin().command(failPoint);
-      });
-
-      it('the cursor for findOne is closed', async function () {
-        const spy = sinon.spy(Collection.prototype, 'find');
-        const error = await collection.findOne({}).catch(error => error);
-        expect(error).to.be.instanceOf(MongoServerError);
-        expect(events.at(0)).to.be.instanceOf(CommandFailedEvent);
-        expect(spy.returnValues.at(0)).to.have.property('closed', true);
-        expect(spy.returnValues.at(0)).to.have.nested.property('session.hasEnded', true);
-      });
-    });
   });
 
   describe('countDocuments()', () => {

test/spec/crud/unified/find.json

@@ -237,6 +237,68 @@
           ]
         }
       ]
+    },
+    {
+      "description": "Find with batchSize equal to limit",
+      "operations": [
+        {
+          "object": "collection0",
+          "name": "find",
+          "arguments": {
+            "filter": {
+              "_id": {
+                "$gt": 1
+              }
+            },
+            "sort": {
+              "_id": 1
+            },
+            "limit": 4,
+            "batchSize": 4
+          },
+          "expectResult": [
+            {
+              "_id": 2,
+              "x": 22
+            },
+            {
+              "_id": 3,
+              "x": 33
+            },
+            {
+              "_id": 4,
+              "x": 44
+            },
+            {
+              "_id": 5,
+              "x": 55
+            }
+          ]
+        }
+      ],
+      "expectEvents": [
+        {
+          "client": "client0",
+          "events": [
+            {
+              "commandStartedEvent": {
+                "command": {
+                  "find": "coll0",
+                  "filter": {
+                    "_id": {
+                      "$gt": 1
+                    }
+                  },
+                  "limit": 4,
+                  "batchSize": 5
+                },
+                "commandName": "find",
+                "databaseName": "find-tests"
+              }
+            }
+          ]
+        }
+      ]
     }
   ]
 }

test/spec/crud/unified/find.yml

@@ -105,3 +105,31 @@ tests:
           - { _id: 2, x: 22 }
           - { _id: 3, x: 33 }
           - { _id: 4, x: 44 }
+  -
+    description: 'Find with batchSize equal to limit'
+    operations:
+      -
+        object: *collection0
+        name: find
+        arguments:
+          filter: { _id: { $gt: 1 } }
+          sort: { _id: 1 }
+          limit: 4
+          batchSize: 4
+        expectResult:
+          - { _id: 2, x: 22 }
+          - { _id: 3, x: 33 }
+          - { _id: 4, x: 44 }
+          - { _id: 5, x: 55 }
+    expectEvents:
+      - client: *client0
+        events:
+          - commandStartedEvent:
+              command:
+                find: *collection0Name
+                filter: { _id: { $gt: 1 } }
+                limit: 4
+                # Drivers use limit + 1 for batchSize to ensure the server closes the cursor
+                batchSize: 5
+              commandName: find
+              databaseName: *database0Name