feat(NODE-6472): findOne and find no longer keep open cursors #4580

durran · 2025-07-09T18:05:50Z

Description

Changes findOne to set options that will not require a cursor or a killCursors command. Updates find to not leave cursors open on the server when batch size and limit are equal.

What is changing?

The find one operation now deprecates options for it specifically which are irrelevant.
The find operation now sets batchSize to batchSize + 1 when the limit is equal to it.
Syncs CRUD spec tests.

Is there new documentation needed for these changes?

API docs on the findOne options.

What is the motivation for this change?

NODE-6472

Release Highlight

`collection.findOne()` and `collection.find()` will no longer potentially leave open cursors on the server

The findOne command will now always set the limit option to 1 and singleBatch to true. The limit, noCursorResponse and batchSize options have also been deprecated, and the command will guarantee no more cursors can be orphaned and no killCursors command will be potentially executed.

find will now set limit to batchSize + 1 when both options were equal, to avoid leaving cursors open.

Double check the following

Ran npm run check:lint script
Self-review completed using the steps outlined here
PR title follows the correct format: type(NODE-xxxx)[!]: description
- Example: feat(NODE-1234)!: rewriting everything in coffeescript
Changes are covered by tests
New TODOs have a related JIRA ticket

durran · 2025-07-22T20:55:27Z

src/collection.ts

-    const res = await cursor.next();
-    await cursor.close();
-    return res;
+    const opts = { ...options };


I made the decision here to do the options changes - creating a new find one operation was much more code and was suspiciously failing 6 tests in load balancer mode. This creating the cursor object works just fine and passes all tests, no killCursors is sent and the cursor on the server side always comes back with id 0.

baileympearson · 2025-07-23T14:24:35Z

src/collection.ts

+    if (opts.noCursorTimeout != null) {
+      delete opts.noCursorTimeout;
+    }
+    if (opts.batchSize != null) {
+      delete opts.batchSize;
+    }


deleting keys off of js object is generally avoided. maybe something like:

Suggested change

if (opts.noCursorTimeout != null) {

delete opts.noCursorTimeout;

}

if (opts.batchSize != null) {

delete opts.batchSize;

}

const { batchSize: _batchSize, noCursorTimeout: _noCursorTimeout, ...opts } = options;

opts.singleBatch = true;

baileympearson · 2025-07-23T14:25:30Z

src/collection.ts

  ): Promise<T | null>;

  async findOne(
    filter: Filter<TSchema> = {},
-    options: FindOptions & Abortable = {}
+    options: Omit<FindOneOptions, ''> & Abortable = {}


Suggested change

options: Omit<FindOneOptions, ''> & Abortable = {}

options: Omit<FindOneOptions, 'timeoutMode'> & Abortable = {}

?

baileympearson · 2025-07-23T14:27:11Z

src/operations/find.ts

@@ -81,6 +81,16 @@ export interface FindOptions<TSchema extends Document = Document>
  timeoutMode?: CursorTimeoutMode;
 }

+/** @public */
+export interface FindOneOptions extends FindOptions {
+  /** @deprecated Will be removed in the next major version. User provided value will be ignored. */


Do we have a ticket to remove these fields from FindOneOptions in v7?

We'd need to add this to the bucket deprecations ticket in V7 or file a new ticket in V7 if the change goes through. (Let's add AC to the ticket to remember to do this). But why are we introducing exposing a brand new interface with deprecated options at all? If we remove these options from the interface, we are going to be back at FindOneOptions being the same as FindOptions - is the intent to replace the definition of this interface in V7 with a copy of FindOptions minus these three?

I expect that once they're removed, we will have:

/** @public */ export type FindOneOptions = Omit<FindOptions, ....>;

Yeah, I think if we're doing more than just removing deprecations, we should do it in a separate ticket from the bucket work (to streamline the bucketed option removal).

baileympearson · 2025-07-23T14:28:27Z

src/operations/find.ts

@@ -195,7 +205,13 @@ function makeFindCommand(ns: MongoDBNamespace, filter: Document, options: FindOp

      findCommand.singleBatch = true;
    } else {
-      findCommand.batchSize = options.batchSize;
+      if (options.batchSize === options.limit) {


the if statement above, which set singleBatch: true was only used for findOne I think. Is that dead code we can remove now?

baileympearson · 2025-07-23T14:31:24Z

src/collection.ts

+      delete opts.batchSize;
+    }
+    const cursor = this.find(filter, opts).limit(1);
+    return await cursor.next();


Thoughts on closing the cursor here regardless if whether or not it "shouldn't be necessary"? See Bernard's comment: https://jira.mongodb.org/browse/SERVER-80713#:~:text=In%20general%2C%20it%20is%20not%20safe%20or%20advisable%20for%20client%20code%20to%20stop%20iterating%20a%20cursor%20until%20the%20driver%20explicitly%20reports%20that%20the%20cursor%20has%20been%20closed%2C%20even%20if%20the%20client%20app%20%22knows%22%20that%20it%20will%20only%20ever%20see%20a%20single%20result.

Also - one of the AC in the ticket:

Ensure no killCursors command is sent to the server.

Do we test this anywhere? (should we test this?)

durran force-pushed the NODE-6472 branch 3 times, most recently from 2f2ee7c to 62c9811 Compare July 9, 2025 19:09

durran added 5 commits July 11, 2025 12:24

feat(NODE-6472): run findOne without cursor

c0824ae

test: fix crud and explain tests

4e92ad1

fix: raw bson option

9203184

fix: handle oid filter case

f9c1364

fix: lint

9fe1c2d

durran force-pushed the NODE-6472 branch from 11b1cf5 to 9fe1c2d Compare July 11, 2025 16:24

durran added 4 commits July 22, 2025 20:00

chore: debug retryability

8d3e0e9

chore: try with existing cursor logic

9604d96

fix: lint

ee0996e

chore: remove dead code

e99589d

durran changed the title ~~feat(NODE-6472): run findOne without cursor~~ feat(NODE-6472): findOne and find no longer keep open cursors Jul 22, 2025

durran commented Jul 22, 2025

View reviewed changes

durran marked this pull request as ready for review July 22, 2025 22:25

durran requested a review from a team as a code owner July 22, 2025 22:25

baileympearson self-assigned this Jul 23, 2025

baileympearson added the Primary Review In Review with primary reviewer, not yet ready for team's eyes label Jul 23, 2025

baileympearson requested changes Jul 23, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(NODE-6472): findOne and find no longer keep open cursors #4580

feat(NODE-6472): findOne and find no longer keep open cursors #4580

durran commented Jul 9, 2025 •

edited

Loading

Uh oh!

durran Jul 22, 2025

Uh oh!

baileympearson Jul 23, 2025

Uh oh!

baileympearson Jul 23, 2025

Uh oh!

baileympearson Jul 23, 2025

Uh oh!

dariakp Jul 23, 2025

Uh oh!

baileympearson Jul 23, 2025

Uh oh!

dariakp Jul 23, 2025

Uh oh!

baileympearson Jul 23, 2025

Uh oh!

baileympearson Jul 23, 2025

Uh oh!

baileympearson Jul 23, 2025

Uh oh!

Uh oh!

	options: Omit<FindOneOptions, ''> & Abortable = {}
	options: Omit<FindOneOptions, 'timeoutMode'> & Abortable = {}

feat(NODE-6472): findOne and find no longer keep open cursors #4580

Are you sure you want to change the base?

feat(NODE-6472): findOne and find no longer keep open cursors #4580

Conversation

durran commented Jul 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

What is changing?

Is there new documentation needed for these changes?

What is the motivation for this change?

Release Highlight

collection.findOne() and collection.find() will no longer potentially leave open cursors on the server

Double check the following

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

durran commented Jul 9, 2025 •

edited

Loading

`collection.findOne()` and `collection.find()` will no longer potentially leave open cursors on the server